diff --git a/docs/README.md b/docs/README.md index 65f0ace8af8..8b6364b42c4 100644 --- a/docs/README.md +++ b/docs/README.md @@ -44,6 +44,10 @@ kb_sync_latest_only - [Concept - URL Rewriting](./concepts/url-rewriting.md) - [Guide - Mocking REST API Calls](./guides/mocking-rest-calls.md) +### Maintenance + +- [Guide - Upgrading Dependencies](./guides/upgrading-pwa.md) + ## Operations ### Setup diff --git a/docs/guides/upgrading-pwa.md b/docs/guides/upgrading-pwa.md new file mode 100644 index 00000000000..5d6ab41fe90 --- /dev/null +++ b/docs/guides/upgrading-pwa.md @@ -0,0 +1,141 @@ + + +# Upgrading Dependencies + +This guide gives a short overview on how to proceed with upgrading PWA dependencies. + +## Customer Projects + +In most cases, customer projects should never do upgrades of dependencies themselves. +Whenever a new PWA version is released the project should consume it completely following the recommended [importing instructions](./customizations.md#import-changes-from-new-release). +Especially the [`package-lock.json`](./customizations.md#dependencies) should be reset to Intershop's version and then (if customized) rewritten using `npm install`. + +## PWA Development + +The following section should only be abided by Intershop PWA developers and projects that want to disconnect from Intershop's PWA update stream. + +### Recommendations for the Process of Updating + +Always use `ng update` for upgrading packages, as it also collects and executes possible source code transformers that do some part of automatic code migration. +We would also recommend updating with `ng update -C` which creates (temporary) commits for each individual update. +This way the process can be tracked easier while doing the update. + +After each package update run some form of code check to verify code consistency. +Full checks can be run with `npm run check`. +You can also run specific subparts of it for verification. + +Do not upgrade too many packages at once as you can easily lose track of the process and have to start anew. + +### 0. Before the Update + +Check if all third-party libraries for the PWA are compatible with the new version. +This is especially important while doing a major Angular version upgrade. + +### 1. Updating Angular Dependencies + +If a new major Angular version should be consumed, follow the steps in the [official update guide](https://update.angular.io) for advanced app complexity. + +`ng update` gives an overview of available angular specific package updates: + +```text +$ ng update +... +Found 99 dependencies. + We analyzed your package.json, there are some packages to update: + + Name Version Command to update + -------------------------------------------------------------------------------- + @angular/cli 9.1.4 -> 9.1.6 ng update @angular/cli + @angular/core 9.1.6 -> 9.1.7 ng update @angular/core + @nguniversal/express-engine 9.1.0 -> 9.1.1 ng update @nguniversal/express-engine +``` + +### 2. Updating Third-Party Project Dependencies + +After updating the Angular specific dependencies, update project libraries (everything you use on the PWA). + +`npm outdated` gives an overview of all upgradable packages in `package.json`: + +```text +$ npm outdated --long +... +@types/jest 25.2.1 25.2.3 25.2.3 intershop-pwa devDependencies https://github.com/DefinitelyTyped/DefinitelyTyped#readme +@types/node 12.12.38 12.12.39 14.0.1 intershop-pwa devDependencies https://github.com/DefinitelyTyped/DefinitelyTyped#readme +angulartics2 9.0.0 9.0.1 9.0.1 intershop-pwa dependencies https://angulartics.github.io/angulartics2/ +bootstrap 4.4.1 4.5.0 4.5.0 intershop-pwa dependencies https://getbootstrap.com/ +... +``` + +Perform updates with `ng update` as well. + +:warning: `@types/node` should always remain on the LTS version. +You can upgrade to specific versions with `ng update @types/node@12`. + +### 3. Update Project Utilities for Testing, Reporting and Linting + +Usually utility dependencies can be upgraded individually as they don't interfere with production code directly. +In most cases you can also postpone these updates for a longer time. + +### 4. Cleanup Dependencies + +Sometimes build processes and libraries require you to install peer dependencies yourself. +This can however change after version upgrades and those dependencies become obsolete. +You can check with `npm ls ` if a package is used or required. + +After removing potential candidates check `npm install` for peer dependency requirements and also run the responsible process to assure continued functionality. + +### 5. Update Utilities for Formatting + +Especially `prettier` upgrades and applying formatting should be done in individual commits (one for the upgrade and a single one only applying the formatting) so customer projects can ignore the second one and run the formatting independently. + +### 6. Refactoring and Deprecations + +Now would be a good time to apply optional code refactoring and replace deprecated code artifacts in individual commits. + +### 7. Restructuring the Update and Documentation + +For customer projects it is most important that the process of upgrading is transparent and applicable. +The commits leading to this point should be partially merged and restructured, so that they are importable via cherry-picking. + +One recommendation would be to combine all manipulations to `package-lock.json` in one single commit if no major refactorings or library replacement took place while upgrading. +Further commits should be focused on descriptive commit messages so the upgrading project can follow them easily. +At the end code re-formatting and optional refactorings should reside in individual commits. + +:warning: Every commit along the way must be consistent. `npm run check` must be runnable without errors, so the customer project can use it to assure consistency. + +## Security Vulnerabilities + +Sometimes `npm install` reports security vulnerabilities: + +```text +$ npm install +... +found 11 vulnerabilities (8 low, 3 high) + run `npm audit fix` to fix them, or `npm audit` for details +``` + +Do not pay too much attention to this. +By doing a complete install on the project, all dependencies (production and development) are audited, but only production dependencies will end up in the production code. +You should however pay attention to the production audit: + +```text +$ npm audit --production + + === npm audit security report === + +found 0 vulnerabilities + in 237 scanned packages +``` + +If a package (in most cases a transitive dependency) poses a security risk, most likely an update of the consuming package is already available. +Go ahead and update the package following the steps above. +The output of `npm audit` will also give useful information about packages. + +### :warning: DO NOT RUN `npm audit fix`! + +This would upgrade versions of transitive dependencies directly in `package-lock.json` and occasionally the affected utilities will stop working.