Patch round YYYY-MM [TEMPLATE]
remypar5 opened this issue · 0 comments
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-updates
is installed in the root, and there are three npm scripts:-
pnpm run update-patch
with.ncurc.patch.cjs
as configuration file -
pnpm run update-minor
with.ncurc.minor.cjs
as configuration file -
pnpm run update-major
with.ncurc.major.cjs
as configuration file -
pnpm run test-update
to run the continuous integration steps as "smoke test".
-
- npm-package-json-lint with
.npmpackagejsonlintrc.json
as configuration file - Require fixed version dependencies for npm:
-
.npmrc
hassave-prefix=
to override the^
or~
with an empty string - none of the existing
package.json
files have^
and~
dependencies. -
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"
-
- 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) - "Security advisories" for this repository are enabled, as well as Dependabot alerts.
Preparation
- 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. -
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.
- Run
pnpm run update-patch
to install new patch versions. - Run
npm run test-update
and see if the build/lint/test scripts are still OK. - Check if the logs contain any (new) warnings. You can compare the logs with GitHub Action logs for the
main
branch. - 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
)
- ideally install
pnpm run update-minor
. - Run
npm run test-update
and see if the build/lint/test scripts are still OK - If a minor update is problematic, you can add the package to the "ignore updates" list in
.ncurc.minor.js
.
major versions
- if there is time, install
pnpm run update-major
. - Run
npm run test-update
and see if the build/lint/test scripts are still OK - 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")
- Upgrade to the latest minor Node LTS version (long term support)
-
package.json
-
engines
-
volta
-
-
.nvmrc
-
.github/workflows/*
: configurenode-version
or referencenode-version-file: ".nvmrc"
-
- Vercel: go to project Settings ➝ General ➝ Node.js version and select the new major version
pnpm
- Upgrade to latest
pnpm
version-
.github/workflows/*
": upgrade pnpm version in GitHub Actions for pnpm -
package.json
underengines
. "^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
- Check the "Security" tab of this GitHub repository and consider the Vulnerabilities
- 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.