Skip to content

Latest commit

 

History

History
105 lines (60 loc) · 5.58 KB

DEPENDENCY_UPDATES.md

File metadata and controls

105 lines (60 loc) · 5.58 KB
Raw

This is a reference on how to perform a safe dependencies update. It consists of step-by-step instruction and a list of known issues. Do not hesitate to contribute when facing outdated information or encountering a new issue.

🦾 Engine support

Version of npm and the node on which the project runs

"node": "^16.15.0",
"npm": "^8.3.x"

♻️ Recommended way to update dependencies

This routine assumes you’ll be using npm as the main package manager.

  • npm update - this command will update all the packages listed to the latest version (specified by the tag config), respecting the semver constraints of both your package and its dependencies (if they also require the same package). It will also install missing packages.

💡 Note that by default npm update will not update the semver values of direct dependencies in your project package.json, if you want to also update values in package.json you can run: npm update --save (or add the save=true option to a configuration file to make that the default behavior).

  1. Open up the project, fetch latest changes, branch out

  2. Run npm update --save to update all the versions in your package.json

The most common/best practice is to never allow automatic updates to versions that have potentially critical changes this applies to major versions so in this case you can rest assured that you will not get critical changes during the upgrade, but if you want to upgrade the major version you will need to do it manually (more about this in step 5) - this will allow you to further check and make sure everything works fine

⚠️ Please, make yourself familiar with conventional semver constraints

  1. Run npm install to update the deps

  2. Run the project, check if everything is okay

  3. Run npm outdated to check for major versions that we can update

Example output

Use the npm install <packageName>@latest command to update the dependencies, in this case we recommend updating each dependency in stages, going back to step 3 and 4 to check that the project is working

  1. If you are done, commit the changes and make a PR

Send your PR to the #review-dev channel for review, and once it is approved to merge with the main branch, update the project data in the Deps update table

Alternative dependency update routine

In case npm update malfunctioning or need to update deps to the latest versions, ignored specified versions, you may want to follow an alternative approach below

Alternative approach
  • npm-check-updates is a handy little library that for historic reasons came into spotlight as a properly working alternative to everbugging native npm outdated && npm update
  • npx is a part of functionality of npm that allows you use npm packages remote, without local installation
  1. Open up the project, fetch latest changes, branch out
  2. Run npx npm-check-updates to get the list of packages that are out of date

Example output

As you may have noticed, ncu is colorizing the possible updates into 3 colors: green, cyan and red.

🟢 Green updates

All the libraries that are in green can be updated safely without really looking at the changelogs (it only concerns patches updates)... So far, we haven't faced any issue when we were updating green dependencies. So usually, just select all of them and update them together.

🔵 Cyan updates

Cyan updates are related to minor updates. So normally, you should be able to update them without any problem but we'd suggest you to do it one by one and by running tests after each update. It'll take time but it'll be safer.

🔴 Red updates

Red updates are for major updates. So somehow it means that the version you've specified in the package.json is really permissive. For sure here, you have to update them one by one and have a real look at the changelogs !

  1. Run npx npm-check-updates -u to update all the versions in your package.json

In this case you'd want to check out changes in package.json and revert particular lines which contain major version update.

  1. Or make use of npx npm-check-updates <package1> <package2> <packageN> command to perform batch categories update

In this case you'd want to specify all the libraries with green updates first

  1. Run npm install to update the deps

  2. Run the project, check if everything is okay

  3. If you are done, commit the changes and make a PR, if not, repeat steps 2-5 but with cyan and red updates

🐛 Known issues

Add information if you're having trouble updating any dependencies, this could be very helpful for future updates

Example

packageName

  • Issue found on: D Month, YYYY
  • Problematic version: x.x.x
  • Last stable version: x.x.x

Space for a free-form description of the problem