@graphcommerce/docs 4.5.0 → 4.5.3

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # Change Log
 
+## 4.5.3
+
+### Patch Changes
+
+- [#1373](https://github.com/graphcommerce-org/graphcommerce/pull/1373) [`48cb78229`](https://github.com/graphcommerce-org/graphcommerce/commit/48cb782299a9efecffbe338e2954af03293e27c8) Thanks [@ErwinOtten](https://github.com/ErwinOtten)! - Update docs, translations
+
+## 4.5.2
+
+### Patch Changes
+
+- [#1354](https://github.com/graphcommerce-org/graphcommerce/pull/1354) [`90fa8d8b9`](https://github.com/graphcommerce-org/graphcommerce/commit/90fa8d8b90e2a3b33cdbb178a87094888c7befdd) Thanks [@ErwinOtten](https://github.com/ErwinOtten)! - Small fixes to docs
+
+## 4.5.1
+
+### Patch Changes
+
+- [#1347](https://github.com/graphcommerce-org/graphcommerce/pull/1347) [`31f463d5c`](https://github.com/graphcommerce-org/graphcommerce/commit/31f463d5c2edff45911b63b1d89e5857244c1754) Thanks [@ErwinOtten](https://github.com/ErwinOtten)! - Upgrading
+
 ## 4.5.0
 
 ### Minor Changes

package/framework/deployment.md

@@ -1,8 +1,12 @@
+<div data-nosnippet>
+
 > **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).
 
+</div>
+
 # Deploy a Graphcommerce app with Vercel
 
 Congratulations, you are ready to deploy your GraphCommerce storefront to

package/framework/environment-variables.md

@@ -1,8 +1,12 @@
+<div data-nosnippet>
+
 > **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).
 
+</div>
+
 # Environment Variables
 
 This guide describes how to store environment variables in your GraphCommerce

package/framework/graphcms.md

@@ -2,11 +2,15 @@
 menu: GraphCMS
 ---
 
+<div data-nosnippet>
+
 > **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).
 
+</div>
+
 # GraphCMS
 
 GraphCMS is integrated as a Content Management System. It is used to store all

package/framework/icons.md

@@ -1,8 +1,12 @@
+<div data-nosnippet>
+
 > **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).
 
+</div>
+
 # Icons
 
 The GraphCommerce UI looks clean and minimalistic due to the use of icons. This
@@ -72,7 +76,7 @@ In /components/Layout/LayoutFull.tsx:
 
 ```tsx
 ...
-import iconCustomerService from '@graphcommerce/next-ui'
+import { iconCustomerService } from '@graphcommerce/next-ui'
 
 ...
 return (

package/framework/readme.md

@@ -2,11 +2,15 @@
 menu: Overview
 ---
 
+<div data-nosnippet>
+
 > **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).
 
+</div>
+
 # GraphCommerce framework overview
 
 GraphCommerce is a front-end framework used for building headless Magento

package/framework/static-generation.md

@@ -6,11 +6,15 @@ metaDescription:
   Generation for Magento nextjs PWA out-of-the-box.'
 ---
 
+<div data-nosnippet>
+
 > **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).
 
+</div>
+
 # Static Site Generation (SSG) in GraphCommerce
 
 Pages that export a function called getStaticProps, will pre-render at

package/framework/translations.md

@@ -71,15 +71,30 @@ Add Linqui to the component's imports:
 import { t, Trans } from '@lingui/macro'
 ```
 
-Add the msgid and translation to the translation files:
+Run `yarn lingui`. All new (missing) translations will be added to translations
+files:
+
+```tsx
+//Example terminal output
+
+┌─────────────┬─────────────┬─────────┐
+│ Language    │ Total count │ Missing │
+├─────────────┼─────────────┼─────────┤
+│ en (source) │     208     │    -    │
+│ nl          │     208     │    1    │
+│ es          │     208     │    1    │
+└─────────────┴─────────────┴─────────┘
+```
+
+Edit the translations files to add your translation:
 
 ```ts
-Example of /locales/es.po
+//Example from /locales/es.po
 
 ...
 
 msgid "Call us now"
-msgstr "Llámanos ahora"
+msgstr ""
 ```
 
 ## Passing `{values}` to translations
@@ -96,7 +111,7 @@ You can pass values in msgid's:
 The syntax in the translation files:
 
 ```ts
-Example of /locales/en.po
+//Example from /locales/en.po
 
 ...
 
@@ -107,6 +122,169 @@ msgid "Cart ({0})"
 msgstr "Cart ({0})"
 ```
 
+## Adding a new language
+
+1. Create a new storeview and configure the locale,
+   `Admin > Store > Configuration > General > General > Locale`. Choose one of
+   the options from the Magento Locale codes (below).
+2. In your .env file, add the desired route and store_code to the
+   `NEXT_PUBLIC_LOCALE_STORES` environment variable. The route will be visible
+   to the user (added to the url) when the user switches storeview.
+
+   It's considered best practice to match the route with the locale code,
+   replacing an underscore for a dash. For example, to add Swedish (Finland),
+   which has locale code sv_FI, add the following:
+
+```tsx
+//Example from .env
+
+NEXT_PUBLIC_LOCALE_STORES =
+  '{"en-us":"default",sv-fi":"[store_code from desired storeview]"}'
+```
+
+3. Run `yarn lingui`:
+
+```tsx
+//Example terminal output
+
+┌─────────────┬─────────────┬─────────┐
+│ Language    │ Total count │ Missing │
+├─────────────┼─────────────┼─────────┤
+│ en (source) │     208     │    -    │
+│ sv          │     208     │   208   │
+└─────────────┴─────────────┴─────────┘
+```
+
+4. A new .po translation file will be generated in the /locales directory, the
+   filename matching the object key or, in case a locale code is used, matching
+   the charactes before the dash (which represent the language).
+
+   In the example above, the filename would result in `sv.po`:
+
+```tsx
+//Example from /locales/sv.po
+
+msgid ""
+msgstr ""
+"POT-Creation-Date: 2022-03-30 14:45+0200\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=utf-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"X-Generator: @lingui/cli\n"
+"Language: sv\n"
+
+msgid "<0>{name}</0> has been added to your shopping cart!"
+msgstr ""
+
+msgid "Above <0/>"
+msgstr ""
+
+msgid "Account"
+msgstr ""
+
+```
+
+5. Add your translations ins the newly created .po file. Run the app and use the
+   store switcher to navigate to your new storeview.
+   [Github copilot ↗](https://copilot.github.com/) provides very accurate
+   suggestions in VS Code with the
+   [Github copilot extention ↗](https://marketplace.visualstudio.com/items?itemName=GitHub.copilot).
+
+### Magento Locale codes
+
+| Locale     | Language (country)                                  |
+| ---------- | --------------------------------------------------- |
+| af_ZA      | Afrikaans (South Africa)                            |
+| sq_AL      | Albanian (Albania)                                  |
+| ar_DZ      | Arabic (Algeria)                                    |
+| ar_EG      | Arabic (Egypt)                                      |
+| ar_KW      | Arabic (Kuwait)                                     |
+| ar_MA      | Arabic (Morocco)                                    |
+| ar_SA      | Arabic (Saudi Arabia)                               |
+| az_Latn_AZ | Azerbaijani (Latijns, Azerbaijan)                   |
+| bn_BD      | Bangla (Bangladesh)                                 |
+| eu_ES      | Basque (Spain)                                      |
+| be_BY      | Belarusian (Belarus)                                |
+| bs_Latn_BA | Bosnian (Latijns, Bosnia & Herzegovina)             |
+| bg_BG      | Bulgarian (Bulgaria)                                |
+| ca_ES      | Catalan (Spain)                                     |
+| zh_Hant_HK | Chinese (traditioneel Chinees, Hong Kong SAR China) |
+| zh_Hant_TW | Chinese (traditioneel Chinees, Taiwan)              |
+| zh_Hans_CN | Chinese (vereenvoudigd Chinees, China)              |
+| hr_HR      | Croatian (Croatia)                                  |
+| cs_CZ      | Czech (Czechia)                                     |
+| da_DK      | Danish (Denmark)                                    |
+| nl_BE      | Dutch (Belgium)                                     |
+| nl_NL      | Dutch (Netherlands)                                 |
+| en_AU      | English (Australia)                                 |
+| en_CA      | English (Canada)                                    |
+| en_IE      | English (Ireland)                                   |
+| en_NZ      | English (New Zealand)                               |
+| en_GB      | English (United Kingdom)                            |
+| en_US      | English (United States)                             |
+| et_EE      | Estonian (Estonia)                                  |
+| fil_PH     | Filipino (Philippines)                              |
+| fi_FI      | Finnish (Finland)                                   |
+| fr_BE      | French (Belgium)                                    |
+| fr_CA      | French (Canada)                                     |
+| fr_FR      | French (France)                                     |
+| fr_LU      | French (Luxembourg)                                 |
+| fr_CH      | French (Switzerland)                                |
+| gl_ES      | Galician (Spain)                                    |
+| ka_GE      | Georgian (Georgia)                                  |
+| de_AT      | German (Austria)                                    |
+| de_DE      | German (Germany)                                    |
+| de_LU      | German (Luxembourg)                                 |
+| de_CH      | German (Switzerland)                                |
+| el_GR      | Greek (Greece)                                      |
+| gu_IN      | Gujarati (India)                                    |
+| he_IL      | Hebrew (Israel)                                     |
+| hi_IN      | Hindi (India)                                       |
+| hu_HU      | Hungarian (Hungary)                                 |
+| is_IS      | Icelandic (Iceland)                                 |
+| id_ID      | Indonesian (Indonesia)                              |
+| it_IT      | Italian (Italy)                                     |
+| it_CH      | Italian (Switzerland)                               |
+| ja_JP      | Japanese (Japan)                                    |
+| km_KH      | Khmer (Cambodia)                                    |
+| ko_KR      | Korean (South Korea)                                |
+| lo_LA      | Lao (Laos)                                          |
+| lv_LV      | Latvian (Latvia)                                    |
+| lt_LT      | Lithuanian (Lithuania)                              |
+| mk_MK      | Macedonian (North Macedonia)                        |
+| ms_MY      | Malay (Malaysia)                                    |
+| nb_NO      | Norwegian Bokmål (Norway)                           |
+| nn_NO      | Norwegian Nynorsk (Norway)                          |
+| fa_IR      | Persian (Iran)                                      |
+| pl_PL      | Polish (Poland)                                     |
+| pt_BR      | Portuguese (Brazil)                                 |
+| pt_PT      | Portuguese (Portugal)                               |
+| ro_RO      | Romanian (Romania)                                  |
+| ru_RU      | Russian (Russia)                                    |
+| sr_Cyrl_RS | Serbian (Cyrillisch, Serbia)                        |
+| sr_Latn_RS | Serbian (Latijns, Serbia)                           |
+| sk_SK      | Slovak (Slovakia)                                   |
+| sl_SI      | Slovenian (Slovenia)                                |
+| es_AR      | Spanish (Argentina)                                 |
+| es_BO      | Spanish (Bolivia)                                   |
+| es_CL      | Spanish (Chile)                                     |
+| es_CO      | Spanish (Colombia)                                  |
+| es_CR      | Spanish (Costa Rica)                                |
+| es_MX      | Spanish (Mexico)                                    |
+| es_PA      | Spanish (Panama)                                    |
+| es_PE      | Spanish (Peru)                                      |
+| es_ES      | Spanish (Spain)                                     |
+| es_US      | Spanish (United States)                             |
+| es_VE      | Spanish (Venezuela)                                 |
+| sw_KE      | Swahili (Kenya)                                     |
+| sv_FI      | Swedish (Finland)                                   |
+| sv_SE      | Swedish (Sweden)                                    |
+| th_TH      | Thai (Thailand)                                     |
+| tr_TR      | Turkish (Turkey)                                    |
+| uk_UA      | Ukrainian (Ukraine)                                 |
+| vi_VN      | Vietnamese (Vietnam)                                |
+| cy_GB      | Welsh (United Kingdom)                              |
+
 ## Next steps
 
 - Learn more about

package/framework/troubleshooting.md

@@ -1,8 +1,12 @@
+<div data-nosnippet>
+
 > **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).
 
+</div>
+
 # Troubleshouting
 
 ## Common build errors

package/getting-started/create.md

@@ -71,7 +71,7 @@ https://user-images.githubusercontent.com/1251986/158647122-dc57002f-a9c2-4661-a
 4. `cd my-project`
 5. `cp -R .env.example .env`
 6. `rm CHANGELOG.md`
-7. `rm -rf node_modules && rm -rf .next`
+7. `rm -r node_modules && rm -r .next`
 
 Edit /package.json. Delete `"scripts": {...}` and rename `scripts_local` to
 `scripts`:
@@ -110,22 +110,29 @@ project, you need to update variables in the /.env file. The .env file contains
 useful information about your storefront.
 
 `MAGENTO_ENDPOINT=""`  
-Magento 2 API url, located at `http://<magento2-server>/graphql`.
+Magento 2 API URL, located at `http://<magento2-server>/graphql`.
 
 `IMAGE_DOMAINS=",media.graphcms.com"`  
 Comma-separated list of image domains. Add media.graphcms.com as default.
 
 `GRAPHCMS_URL=""`  
-GraphCMS API url. Once logged in, copy it from Project Settings > Api Access >
+GraphCMS API URL. Once logged in, copy it from Project Settings > Api Access >
 Content API
 
-`NEXT_PUBLIC_LOCALE_STORES='{"en": "en_US", "nl": "default"}'`  
-List of routes and store_codes. In the above example, adding URL suffix /nl/
-would result in the storeview 'default' is loaded. GraphCommerce uses the
-browser language to determine which storeview to load. A URL suffix will be
-added as a result, with the exception of the first option in the list.
+`NEXT_PUBLIC_LOCALE_STORES='{"en-us": "default", "en-ca": "canada"}'`  
+List of routes and store_codes:
 
-> If need to fetch a list of available store_codes, run `yarn dev` when you
+- When the user switches to the Canadian storeview, the suffix /en-ca is added
+  to the URL.
+- The first storeview in the object is loaded by default. No suffix is added to
+  the URL.
+- The key (en-ca) is used to load the storeview
+  [translation](../framework/translations.md)
+- When a users' browser language matches a storeviews' locale
+  (`Admin > Store > Configuration > General > General > Locale`), the user is
+  automatically redirected to the corresponding storeview.
+
+> If you need to fetch a list of available store_codes, run `yarn dev` when you
 > entered your `MAGENTO_ENDPOINT`. The app won't build, but the GraphQL explorer
 > will start at `http://localhost:3000/api/graphql`. Enter the following query:
 >

package/getting-started/graphcms-component.md

@@ -3,11 +3,15 @@ menu: 5. Build a GraphCMS component
 metaTitle: Build a GraphCMS component
 ---
 
+<div data-nosnippet>
+
 > **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).
 
+</div>
+
 # Build a GraphCMS component
 
 Previously, you created a GraphCommerce app and started building a custom
@@ -45,7 +49,7 @@ frontend React framework that uses Next.js for server-side rendering.
 
 <figure>
 
-![Adding a Single line text field]()
+![Adding a Single line text field](https://user-images.githubusercontent.com/1251986/159904004-cf774bd1-da01-4478-ac6e-b1567f9bafc7.png)
 
   <figcaption>Adding a Single line text field called "Identity"</figcaption>
 </figure>

package/getting-started/header.md

@@ -3,11 +3,15 @@ menu: 3. Build a custom header
 metaTitle: Build a custom header
 ---
 
+<div data-nosnippet>
+
 > **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).
 
+</div>
+
 # Build a custom header in GraphCommerce
 
 Previously, you created a GraphCommerce app and started building your custom

package/getting-started/pages.md

@@ -3,11 +3,15 @@ menu: 4. Build pages
 metaTitle: Build pages
 ---
 
+<div data-nosnippet>
+
 > **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).
 
+</div>
+
 # Build pages in GraphCommerce
 
 Previously, you created a custom storefront and started customizing your

package/getting-started/readme.md

@@ -9,11 +9,15 @@ metaDescription:
   template for Magento storefronts'
 ---
 
+<div data-nosnippet>
+
 > **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).
 
+</div>
+
 # GraphCommerce magento-graphcms example overview
 
 GraphCommerce offers a magento-graphcms example that provides an approachable

package/getting-started/start-building.md

@@ -3,11 +3,15 @@ menu: 2. Customize a storefront
 metaTitle: Customize a storefront
 ---
 
+<div data-nosnippet>
+
 > **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).
 
+</div>
+
 # Start building a GraphCommerce custom storefront
 
 Previously, you [created a new GraphCommerce app](../getting-started/create.md).

package/package.json

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

package/readme.md

@@ -8,11 +8,15 @@ metaDescription:
   extension.'
 ---
 
+<div data-nosnippet>
+
 > **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).
 
+</div>
+
 # GraphCommerce
 
 GraphCommerce is a front-end framework used for building headless Magento

package/roadmap.md

@@ -9,16 +9,14 @@ The following overview contains the status of items on the GraphCommerce roadmap
 
 ## In progress
 
-- [x] Framework updates (Mui5)
-- [x] Translation updates (DE, NL, ES, FR, IT)
-- [x] Documentation and installation guide
-- [ ] Quality improvements (Reduce components, naming)
+- [ ] Adyen payment service (Braintree, Mollie, Klarna, Paypal already
+      implemented)
+- [ ] Wishlist
 
 ## Planned
 
-- [ ] Search integration (external service)
-- [ ] Checkout UI and accessibility improvements
-- [ ] Payment service provider integration
+- [ ] Buckaroo payment service
+- [ ] Multisafepay payment service
 
 ## Future
 

package/upgrading.md

@@ -1,37 +1,31 @@
+<div data-nosnippet>
+
 > **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.
+</div>
 
-To upgrade your project to the latest version we need to do a few steps:
+# Upgrading
 
-## What you'll do
+This guide describes how to upgrade your GraphCommerce project files and its
+dependencies, while keeping your customizations.
 
-After you've finished this guide, you'll have accomplished the following:
+### After you've finished this upgrading 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
+- Incorporated all the latest changes in your project, while keeping your
   customizations
 
-## Create an apply a patch file
-
-1. Get the version of **your own project**
+## Step 1: Creating and applying a patch file
 
-   In your local package.json you'll find something like this:
+1. In package.json, find your version:
 
    ```json
+   // Example from package.json
+
    {
      "dependencies": {
        //...
@@ -41,128 +35,86 @@ After you've finished this guide, you'll have accomplished the following:
    }
    ```
 
-   We need the version of `@graphcommerce/next-ui` later.
-
-2. Create a clone of the `https://github.com/graphcommerce-org/graphcommerce`
-   repo.
+2. Download a fresh copy of the repository:
 
    ```bash
-   git clone git@github.com:graphcommerce-org/graphcommerce.git
+   git clone git@github.com:graphcommerce-org/graphcommerce.git upgrade
    ```
 
-   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:
+3. Navigate to the /upgrade directory you've just created. Run the following
+   command, but replace `OLD_VERSION` with your version of
+   `@graphcommerce/next-ui`:
 
    ```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
+4. Move the `changes.patch` file from the /upgrade directory to the root of your
+   project.
 
-   ```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:
+5. Apply the patch to your project (It's recommended to apply changes on a new
+   branch):
 
    ```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.
+## Step 2: Resolving issues
 
-   Tip: create an intermediate commit
+### Resolving package.json issues
 
-   ```bash
-   git commit -am"refactor: applied patches"
-      rm changes.patch
-   ```
+If running the upgrade steps results in a `package.json.rej` file and the diff
+is large, it can be easier to manually update the `package.json` file.
 
-## What has happened?
+Compare your local /package.json with the example's
+`/upgrade/examples/magento-graphcms/package.json` you just downloaded and:
 
-> `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.
+1. Replace your local `dependencies` with the example's `dependencies`. Keep any
+   additional installed local dependencies and
+   [remove PSP's](./getting-started/create.md#remove-unused-psps) your backend
+   doesn't support.
+2. Replace your local `devDependencies` with the example's `devDependencies`
+3. Replace your local `scripts` with the example's `scripts_local`
 
-## Resolving package.json issues
+After updating the package.json file, run the following to install the latest
+packages:
 
-If you've got a package.json.rej file and the diff is very large, it might be
-easier to manually update the file.
+- `rm yarn.lock && yarn` Remove lock and install the dependencies
+- `yarn codegen` Converts all .graphql files to typescript files
+- `yarn dev` Run the app
 
-We want to have the latest `dependencies`, `devDependencies` and `scripts` from
-`graphcommerce/examples/magento-example/package.json`.
+### Resolving diff issues
 
-- 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`
+When you run `git apply ...` (step 4), git will try and apply all the diffs from
+the patch file to your project files. When applying a diff fails, a
+[reject ↗](https://git-scm.com/docs/git-apply#Documentation/git-apply.txt---reject)
+`.rej` file will be created for _each_ file that could not be upgraded.
 
-It might be that you have installed additional local dependencies, you can keep
-those.
+It can very well be that some files can't be updated automatically, because of
+modifications you made. The CLI will show you the location of these files, as
+well as the number of hunks:
 
-```bash
-rm yarn.lock
-yarn
-yarn codegen
-rm package.json.rej
+```
+Applying patch pages/_app.tsx with 2 rejects...
+Rejected hunk #1.
+Rejected hunk #2.
 ```
 
-## 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
+The suggested changes have to be reviewed _manually_ (a diff tool can provide
+insight, but won't be able to apply diffs). Manually apply the suggested changes
+you want. Discard the .rej files of the suggested changes you don't want. Before
+you commit, make sure to delete all the .rej files:
 
 ```bash
-git commit -am"refactor: processed manual .rej files"
+find . -type f -name '*.rej' -delete
 ```
 
-## Running and validating your project
+After resolving the diff issues, run and validate your local environment:
 
 - `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! 🎉
+## Next steps
 
-Commit, push and deploy!
+- Learn how to [contribute to GraphCommerce](./contributing.md)