@graphcommerce/docs 4.4.3 → 4.5.0

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Change Log
 
+## 4.5.0
+
+### Minor Changes
+
+- [#1341](https://github.com/graphcommerce-org/graphcommerce/pull/1341) [`a06c86706`](https://github.com/graphcommerce-org/graphcommerce/commit/a06c86706c8b76ce91cfa1e526fe16aa20c53991) Thanks [@paales](https://github.com/paales)! - Added upgrade instructions
+
+### Patch Changes
+
+- [#1338](https://github.com/graphcommerce-org/graphcommerce/pull/1338) [`a8886ce4c`](https://github.com/graphcommerce-org/graphcommerce/commit/a8886ce4c059e85b83158b4bc1d8e2f04626d49f) Thanks [@paales](https://github.com/paales)! - Docs improvements
+
 ## 4.4.3
 
 ### Patch Changes

package/getting-started/create.md

@@ -65,14 +65,13 @@ https://user-images.githubusercontent.com/1251986/158647122-dc57002f-a9c2-4661-a
 
 ### Download the example
 
-1. `git clone git@github.com:graphcommerce-org/graphcommerce.git graphcommerce`
+1. `git clone git@github.com:graphcommerce-org/graphcommerce.git`
 2. `mkdir my-project`
 3. `cp -R graphcommerce/examples/magento-graphcms/. my-project`
-4. `rm -rf graphcommerce`
-5. `cd my-project`
-6. `cp -R .env.example .env`
-7. `rm CHANGELOG.md && touch CHANGELOG.md`
-8. `rm -rf node_modules && rm -rf .next`
+4. `cd my-project`
+5. `cp -R .env.example .env`
+6. `rm CHANGELOG.md`
+7. `rm -rf node_modules && rm -rf .next`
 
 Edit /package.json. Delete `"scripts": {...}` and rename `scripts_local` to
 `scripts`:
@@ -99,7 +98,7 @@ Edit /package.json. Delete `"scripts": {...}` and rename `scripts_local` to
 To order to be able to connect your GraphCommerce app to your Magento backend
 and/or GraphCMS project, you'll need:
 
-- Magento 2.4.3 - Clean install, or a production or development environment
+- Magento 2.4.3 - Clean install, a production or a development environment
 - GraphCMS - A GraphCMS project with the required schema.
   [Clone the demo GraphCMS project ↗](https://app.graphcms.com/clone/caddaa93cfa9436a9e76ae9c0F34d257)
   as your starting point.
@@ -142,7 +141,7 @@ added as a result, with the exception of the first option in the list.
 ### Remove unused PSP's
 
 The example has Payment Service Providers integrated (Mollie, Braintree). Remove
-the ones you don't want to use.
+the ones your Magento backend doesn't support.
 
 - Remove `"@graphcommerce/[psp]"` from package.json
 - Remove all [psp] references from `pages/checkout/payment.tsx`
@@ -156,7 +155,10 @@ the ones you don't want to use.
 Visit the development environment running at http://localhost:3000  
 Visit the GraphQL Playground running at http://localhost:3000/api/graphql
 
-> No success? Refer to [common build errors](../framework/troubleshooting.md)
+> No success? Refer to [common build errors](../framework/troubleshooting.md) or
+> ask your question in the public
+> [Slack community ↗](https://join.slack.com/t/graphcommerce/shared_invite/zt-11rmgq1ad-F~0daNtKcSvtcC4eQRzjeQ)
+> chat
 
 ## Next steps
 

package/getting-started/header.md

@@ -101,8 +101,8 @@ https://user-images.githubusercontent.com/1251986/154979091-89c72d68-c62f-451c-a
 
 ### Replace Search input with Search Fab
 
-- In /components/Layout/LayoutFull.tsx, replace
-  `<SearchButton onClick={onSearchStart} label=' ' />` with:
+- In /components/Layout/LayoutFull.tsx, replace `<SearchLink href='/search' />`
+  with:
 
 ```tsx
 <PageLink href='/search' passHref>
@@ -144,11 +144,6 @@ https://user-images.githubusercontent.com/1251986/154979091-89c72d68-c62f-451c-a
 
 - Make a copy of /node_modules/@graphcommerce/next-ui/LayoutParts/MenuFab.tsx
   and move it to the directory /components/Layout/MenuFab.tsx
-- In /components/Layout/MenuFab.tsx, change
-  `const MotionDiv = styled(m.div)({})` to:
-  ```ts
-  const MotionDiv = styled('div')({})
-  ```
 - Remove the `style={{...}}` prop from both the `<MotionDiv>` components to
   remove the Fab scroll animation
 - Remove `const { opacity, scale, shadowOpacity } = useFabAnimation()`

package/getting-started/pages.md

@@ -102,7 +102,6 @@ export const getStaticProps: GetPageStaticProps = async (context) => {
       ...(await page).data,
       apolloState: await conf.then(() => client.cache.extract()),
     },
-    revalidate: 60 * 20,
   }
 }
 ```
@@ -209,7 +208,6 @@ export const getStaticProps: GetPageStaticProps = async (context) => {
       ...(await page).data,
       apolloState: await conf.then(() => client.cache.extract()),
     },
-    revalidate: 60 * 20,
   }
 }
 ```

package/getting-started/vscode.md

@@ -13,7 +13,7 @@ as GraphCommerce. Visual Studio Code is free and available on all platforms.
 This guide covers which useful VS Code extensions to install for an optimal
 development experience.
 
-Recommended extensions
+Required extensions
 
 - [ESLint ↗](https://marketplace.visualstudio.com/items?itemName=dbaeumer.vscode-eslint) -
   Linter tool for identifying and reporting on patterns in JavaScript
@@ -22,24 +22,18 @@ Recommended extensions
 - [GraphQL ↗](https://marketplace.visualstudio.com/items?itemName=GraphQL.vscode-graphql) -
   Adds syntax highlighting, validation, hover information and autocompletion for
   graphql files
+- [Yaml ↗](https://marketplace.visualstudio.com/items?itemName=redhat.vscode-yaml)
+
+Recommended extensions:
+
 - [DotENV ↗](https://marketplace.visualstudio.com/items?itemName=mikestead.dotenv) -
   Adds support for dotenv file syntax
-- [JavaScript Booster ↗](https://marketplace.visualstudio.com/items?itemName=sburg.vscode-javascript-booster) -
-  Advanced JavaScript/TypeScript refactorings and commands
 - [gettext ↗](https://marketplace.visualstudio.com/items?itemName=mrorz.language-gettext) -
   Adds syntax highlight to po translation files
-
-Optional extentions
-
-- [Color Highlight ↗](https://marketplace.visualstudio.com/items?itemName=naumovs.color-highlight)
-- [Material Theme ↗](https://marketplace.visualstudio.com/items?itemName=Equinusocio.vsc-material-theme)
-- [Material Theme Icons ↗](https://marketplace.visualstudio.com/items?itemName=Equinusocio.vsc-material-theme-icons)
-- [Output Colorizer ↗](https://marketplace.visualstudio.com/items?itemName=IBM.output-colorizer)
-- [Readability Check ↗](https://marketplace.visualstudio.com/items?itemName=jemcclin.readabilitycheck)
 - [Github Actions ↗](https://marketplace.visualstudio.com/items?itemName=me-dutour-mathieu.vscode-github-actions)
-- [MDX ↗](https://marketplace.visualstudio.com/items?itemName=silvenon.mdx)
-- [Markdown Preview Github Styling ↗](https://marketplace.visualstudio.com/items?itemName=bierner.markdown-preview-github-styles)
-- [Yaml ↗](https://marketplace.visualstudio.com/items?itemName=redhat.vscode-yaml)
+- [JavaScript Booster ↗](https://marketplace.visualstudio.com/items?itemName=sburg.vscode-javascript-booster) -
+  Advanced JavaScript/TypeScript refactorings and commands
+- [Color Highlight ↗](https://marketplace.visualstudio.com/items?itemName=naumovs.color-highlight)
 
 ## Next steps
 

package/package.json

@@ -2,7 +2,7 @@
   "name": "@graphcommerce/docs",
   "homepage": "https://www.graphcommerce.org/docs",
   "repository": "github:graphcommerce-org/graphcommerce/docs",
-  "version": "4.4.3",
+  "version": "4.5.0",
   "sideEffects": true,
   "devDependencies": {
     "@graphcommerce/prettier-config-pwa": "^4.0.2"

package/readme.md

@@ -1,6 +1,6 @@
 ---
 menu: Overview
-order: getting-started,framework, contributing, roadmap
+order: getting-started,framework, upgrading, contributing, roadmap
 metaTitle: Start React, Next.js Magento PWA development here - GraphCommerce
 metaDescription:
   'GraphCommerce is the open-source PWA Studio Magento 2 alternative.
@@ -40,7 +40,7 @@ https://user-images.githubusercontent.com/1251986/154977573-4015e77c-43e7-481e-a
 - Nextjs
 - GraphQL
 - Mui
-- Apollo
+- Apollo Client
 - GraphQL Code Generator
 - Framer Motion
 

package/roadmap.md

@@ -11,7 +11,7 @@ The following overview contains the status of items on the GraphCommerce roadmap
 
 - [x] Framework updates (Mui5)
 - [x] Translation updates (DE, NL, ES, FR, IT)
-- [ ] Documentation and installation guide
+- [x] Documentation and installation guide
 - [ ] Quality improvements (Reduce components, naming)
 
 ## Planned

package/upgrading.md

@@ -0,0 +1,168 @@
+> **Developer preview**  
+> This is a developer preview of GraphCommerce. The documentation will be
+> updated as GraphCommerce introduces
+> [new features and refines existing functionality](https://github.com/graphcommerce-org/graphcommerce/releases).
+
+# Upgrading
+
+We are going to upgrade your project to the latest version, for all the new
+features and fixes that we've made. We can automate most of this process, but
+there are some manual steps involved.
+
+We try to keep changes to the examples minimal as possible, but sometimes this
+is inevitable. 95% of the changes are made inside the @graphcommerce packages,
+but for some changes we need to make changes in the example to get everything
+working.
+
+To upgrade your project to the latest version we need to do a few steps:
+
+## What you'll do
+
+After you've finished this guide, you'll have accomplished the following:
+
+- Created a changes.patch file and applied it to your project
+- Upgraded all dependencies to the latest version
+- Incorporated all latest changes in your project while maintaining all your
+  customizations
+
+## Create an apply a patch file
+
+1. Get the version of **your own project**
+
+   In your local package.json you'll find something like this:
+
+   ```json
+   {
+     "dependencies": {
+       //...
+       "@graphcommerce/next-ui": "^4.2.0"
+       //...
+     }
+   }
+   ```
+
+   We need the version of `@graphcommerce/next-ui` later.
+
+2. Create a clone of the `https://github.com/graphcommerce-org/graphcommerce`
+   repo.
+
+   ```bash
+   git clone git@github.com:graphcommerce-org/graphcommerce.git
+   ```
+
+   Or if you have a local copy already available, make sure that you are on the
+   latest commit of the `main` branch.
+
+3. Create a patch from the example
+
+   Replace `OLD_VERSION` in the command below with the version number of
+   `@graphcommerce/next-ui` you just looked up:
+
+   ```bash
+   git diff --relative=examples/magento-graphcms "@graphcommerce/next-ui@OLD_VERSION" examples/magento-graphcms ':!examples/magento-graphcms/CHANGELOG.md' > changes.patch
+   ```
+
+   Run the above command (with OLD_VERSION replaced with something like `1.2.3`)
+   in the `graphcommerce` repo. you should have a changes.patch file in root of
+   the `graphcommerce` repo.
+
+4. Move the file to your project's root directory
+
+   ```bash
+   mv changes.patch ../your-project-root
+   cd ../your-project-root
+   ```
+
+   Tip: create a separate branch
+
+   ```bash
+   git checkout -b my-upgrade
+   ```
+
+   You should now have a changes.patch file in the root of your project.
+
+5. Apply the patch to your project
+
+   Make sure your working directory is clean (except for the changes.patch file)
+   and run:
+
+   ```bash
+   git apply --reject --ignore-whitespace --exclude=README.md changes.patch
+   ```
+
+   You should now have all the changes from the example applied to your project.
+
+   Tip: create an intermediate commit
+
+   ```bash
+   git commit -am"refactor: applied patches"
+      rm changes.patch
+   ```
+
+## What has happened?
+
+> `git apply --reject` will try and apply all the diffs to your project and if
+> it isn't able to do so, it will create a `.rej` file for _each_ file that it
+> couldn't apply the changes to.
+>
+> `git` expects you to manually apply the changes in the `.rej` files to your
+> project.
+
+## Resolving package.json issues
+
+If you've got a package.json.rej file and the diff is very large, it might be
+easier to manually update the file.
+
+We want to have the latest `dependencies`, `devDependencies` and `scripts` from
+`graphcommerce/examples/magento-example/package.json`.
+
+- Replace your local `dependencies` with the example `dependencies` (and
+  [remove PSPs](./getting-started/create.md#remove-unused-psps) your backend
+  doesn't support)
+- Replace your local `devDependencies` with the example `devDependencies`
+- Replace your local `scripts` with the example `scripts_local`
+
+It might be that you have installed additional local dependencies, you can keep
+those.
+
+```bash
+rm yarn.lock
+yarn
+yarn codegen
+rm package.json.rej
+```
+
+## Resolving patch conflicts
+
+It can very wel be that some files can't be updated automatically, because of
+your modifications. You'll see something like `Rejected hunk #2` in the cli. The
+above command will create rejection files like `Component.ts.rej` for each hunk
+it couldn't apply.
+
+All the '.rej' files **must** be handled manually by:
+
+- Manually applying the diff in the .rej file to the original file because you
+  want the changes. (recommended)
+- Discarding the .rej file because you've modified the project already.
+
+Make sure all .rej files are deleted (`find . -type f -name '*.rej' -delete`)
+
+Tip: make a commit
+
+```bash
+git commit -am"refactor: processed manual .rej files"
+```
+
+## Running and validating your project
+
+- `yarn codegen` should run without errors
+- `yarn tsc:lint` should run without errors
+- `yarn dev` should run without errors
+
+If the above commands are working correctly you should now have a working
+project. Validate if everything looks right, especially the parts that have
+manual changes.
+
+You are done with the upgrade! 🎉
+
+Commit, push and deploy!