Pro-tip: ignore warnings about deprecated packages until you have completed upgrade of major releases. Often major releases will fix deprecated warnings.
Configuration
The following configuration is a prerequisite for this workflow. All of this should have already been installed and configured.
[x] npm-check-updates is installed in the root, and there are three npm scripts:
[x] pnpm run update-patch with .ncurc.patch.cjs as configuration file
[x] pnpm run update-minor with .ncurc.minor.cjs as configuration file
[x] pnpm run update-major with .ncurc.major.cjs as configuration file
[x] pnpm run test-update to run the continuous integration steps as "smoke test".
[x] .npmrc has save-prefix= to override the ^ or ~ with an empty string
[x] none of the existing package.json files have ^ and ~ dependencies.
[x] package-json-lint checks the following rules:
"no-caret-version-dependencies": "error"
"no-caret-version-devDependencies": "error"
"no-tilde-version-dependencies": "error"
"no-tilde-version-devDependencies": "error"
[x] the pnpm-lock.yaml lock file for the package manager has been committed to the git repo (and lock files for other package managers have been added to .gitignore to prevent accidentally committing those)
[x] Check the /.patches/ directory in the root (if present), and see if there are any npm packages that have overrides for their code.
When for a patch/minor/major update these package are updated, you must also create a new version of the patch file. Create a task for this in this issue.
Sometimes the patch is no longer necessary, because the bug that the patch is for has been fixed in the actual package. Read the commit message for the patch, or read the GitHub PR comments or the related GitHub issue comments to find out what the patch was for.
Ideally the patch files have a code comment in .patches/README.md explaining the conditions when the patch is no longer required.
npm dependencies
We use the npm-check-updates package to upgrade to new versions of npm packages, and have consistent versions across all packages in our mono-repository.
There are three configuration files:
.ncurc.patch.cjs: include packages in this array to prevent upgrading patch versions and higher.
.ncurc.minor.cjs: prevent upgrading to new minor versions and higher.
.ncurc.major.cjs: prevent upgrading to new major versions and higher.
[x] Check the configuration files above, to see if some of the updates no longer need to be blocked. Ideally the entries in these files have a code comment explaining the conditions where the upgrade no longer needs to be prevented.
patch versions
We don't allow ~1.0.0 style dependencies, so patch versions will not be installed automatically (1.0.0 to 1.0.1). That's why it is important to frequently install patches yourself.
[x] Run pnpm run update-patch to install new patch versions.
[x] Run npm run test-update and see if the build/lint/test scripts are still OK.
[x] Check if the logs contain any (new) warnings. You can compare the logs with GitHub Action logs for the main branch.
[x] If a patch update is problematic, you can temporarily add the package to the "ignore updates" list in .ncurc.patch.js.
Not all package maintainers use semantic versioning, especially 0.x.x versions, and alpha and beta versions. Unfortunately they will be installed as part of update-patch, so update-patch isn't as safe as you might think. You might want to read change logs of patch upgrades below 1.0.0 to see if there are breaking API changes.
[ ] Check if any packages have upgrades like 0.1.2 ➝ 0.1.9, and pay extra attention to these packages.
Create a pull request at this stage already, since minor upgrades and major upgrades might take some effort. Patches sometimes contain security vulnerability fixes.
minor versions
We don't allow ^1.0.0 style dependencies (1.0.0 to 1.0.1)
[x] ideally install pnpm run update-minor.
[x] Run npm run test-update and see if the build/lint/test scripts are still OK
[x] If a minor update is problematic, you can add the package to the "ignore updates" list in .ncurc.minor.js.
major versions
[x] if there is time, install pnpm run update-major.
[x] Run npm run test-update and see if the build/lint/test scripts are still OK
[x] If a major update is problematic, you can add the package to the "ignore updates" list in .ncurc.major.js.
Make an issue for minor/major upgrades that require so much time we better schedule it in a sprint.
deprecations
Run pnpm install. If the log still contains deprecation warnings at this stage, check if they are direct dependencies. Are the dependencies mentioned in our own package.json files? Then it its probably worthwhile to investigate why the package is deprecated. A good information source is often the README on the page about the package on npmjs.com. They will likely mention the reason for deprecating the page (e.g: no time to install security patches, you are on your own!) and they might even suggest alternative packages.
GitHub Action
Dependabot pull requests are a great way to detect outdated dependencies in GitHub Actions.
[ ] Upgrade all GitHub Action dependencies
Node.js
Check the Node.js website to see what the long term support version is ("Node LTS")
[x] Upgrade to the latest minor Node LTS version (long term support)
[x] package.json
[x] engines
[x] volta
[x] .nvmrc
[x] .github/workflows/*: configure node-version or reference node-version-file: ".nvmrc"
[ ] Vercel: go to project Settings ➝ General ➝ Node.js version and select the new major version
pnpm
[x] Upgrade to latest pnpm version
[x] .github/workflows/*": upgrade pnpm version in GitHub Actions for pnpm
[x] package.json under engines. "^version" is usually okay, an exact version dependency is undesirable for developer experience, unless everyone develops in Docker containers. You can install an exact version of pnpm in GitHub Action if you want to.
Vulnerabilities
[x] Check the "Security" tab of this GitHub repository and consider the Vulnerabilities
[x] Upgrade all vulnerable dependencies, or dismiss the alerts with a good reason.
Docker images
Currently this repo doesn't have a docker-compose.yml where image needs to be updated, or any Dockerfile where FROM needs to be updated.
Pro-tip: ignore warnings about deprecated packages until you have completed upgrade of major releases. Often major releases will fix deprecated warnings.
Configuration
The following configuration is a prerequisite for this workflow. All of this should have already been installed and configured.
npm-check-updatesis installed in the root, and there are three npm scripts:pnpm run update-patchwith.ncurc.patch.cjsas configuration filepnpm run update-minorwith.ncurc.minor.cjsas configuration filepnpm run update-majorwith.ncurc.major.cjsas configuration filepnpm run test-updateto run the continuous integration steps as "smoke test"..npmpackagejsonlintrc.jsonas configuration file.npmrchassave-prefix=to override the^or~with an empty stringpackage.jsonfiles have^and~dependencies.package-json-lintchecks the following rules:"no-caret-version-dependencies": "error""no-caret-version-devDependencies": "error""no-tilde-version-dependencies": "error""no-tilde-version-devDependencies": "error"pnpm-lock.yamllock file for the package manager has been committed to the git repo (and lock files for other package managers have been added to.gitignoreto prevent accidentally committing those)Preparation
/.patches/directory in the root (if present), and see if there are any npm packages that have overrides for their code..patches/README.mdexplaining the conditions when the patch is no longer required.npm dependencies
We use the
npm-check-updatespackage to upgrade to new versions of npm packages, and have consistent versions across all packages in our mono-repository.There are three configuration files:
.ncurc.patch.cjs: include packages in this array to prevent upgrading patch versions and higher..ncurc.minor.cjs: prevent upgrading to new minor versions and higher..ncurc.major.cjs: prevent upgrading to new major versions and higher.[x] Check the configuration files above, to see if some of the updates no longer need to be blocked. Ideally the entries in these files have a code comment explaining the conditions where the upgrade no longer needs to be prevented.
patch versions
We don't allow
~1.0.0style dependencies, so patch versions will not be installed automatically (1.0.0to1.0.1). That's why it is important to frequently install patches yourself.pnpm run update-patchto install new patch versions.npm run test-updateand see if the build/lint/test scripts are still OK.mainbranch..ncurc.patch.js.Not all package maintainers use semantic versioning, especially
0.x.xversions, andalphaandbetaversions. Unfortunately they will be installed as part ofupdate-patch, soupdate-patchisn't as safe as you might think. You might want to read change logs of patch upgrades below1.0.0to see if there are breaking API changes.0.1.2➝0.1.9, and pay extra attention to these packages.Create a pull request at this stage already, since minor upgrades and major upgrades might take some effort. Patches sometimes contain security vulnerability fixes.
minor versions
We don't allow
^1.0.0style dependencies (1.0.0to1.0.1)pnpm run update-minor.npm run test-updateand see if the build/lint/test scripts are still OK.ncurc.minor.js.major versions
pnpm run update-major.npm run test-updateand see if the build/lint/test scripts are still OK.ncurc.major.js.Make an issue for minor/major upgrades that require so much time we better schedule it in a sprint.
deprecations
Run
pnpm install. If the log still contains deprecation warnings at this stage, check if they are direct dependencies. Are the dependencies mentioned in our ownpackage.jsonfiles? Then it its probably worthwhile to investigate why the package is deprecated. A good information source is often the README on the page about the package on npmjs.com. They will likely mention the reason for deprecating the page (e.g: no time to install security patches, you are on your own!) and they might even suggest alternative packages.GitHub Action
Dependabot pull requests are a great way to detect outdated dependencies in GitHub Actions.
Node.js
Check the Node.js website to see what the long term support version is ("Node LTS")
package.jsonenginesvolta.nvmrc.github/workflows/*: configurenode-versionor referencenode-version-file: ".nvmrc"pnpm
pnpmversion.github/workflows/*": upgrade pnpm version in GitHub Actions for pnpmpackage.jsonunderengines. "^version" is usually okay, an exact version dependency is undesirable for developer experience, unless everyone develops in Docker containers. You can install an exact version of pnpm in GitHub Action if you want to.Vulnerabilities
Docker images
Currently this repo doesn't have a
docker-compose.ymlwhereimageneeds to be updated, or anyDockerfilewhereFROMneeds to be updated.