Skip to content

Guide to upgrading dependencies

Jump to bottom
Sven van Steenis edited this page Oct 24, 2022 · 6 revisions

Index

Guide to upgrading dependencies

As a rule of thumb, we should strive to stay as up to date as possible with the dependencies used in this project. This is to ensure that we always have the latest features and security updates. That being said it is not realistic to always be 100% up to date, as it would require significant resources to keep up with all the updates. Nevertheless it is recommended to regularly check for updates and to stay informed on changes implemented in the dependencies we rely on.

When upgrading dependencies, it is important to check to make sure that everything is still working correctly. This should be done in your local development environment first, and then on the hosted development environment after you have committed and pushed your changes.

Checking for updates

Because we use different package managers for different parts of the project, you can't use a single command to check for and apply upgrades. The following commands will give you a list of outdated dependencies for each part of the project:

  • Project root: $ pnpm outdated
  • Web folder: $ pnpm outdated
  • Studio folder: $ yarn outdated
  • Search folder: $ npm outdated

This project is set up with the tool Snyk to check for security issues. On occasion Snyk may open a pull-request to update a specific dependency. These pull-requests should be prioritized as they indicate a security threat in one of our dependencies. These can either be resolved by upgrading to the version that Snyk indicates, or by upgrading to a version greater than that - but should always be tested like any other dependency upgrade to ensure compatibility. It should be noted that Snyk currently does not handle PNPM or Yarn, and will only commit a change to the package.json file. If you choose to merge the Snyk PR you will need to do a git pull locally and (re)install your dependencies to update the relevant lockfile(s).

Update types

Generally speaking, patch (e.g. v2.0.1) and minor (e.g. v2.1.0) version updates should be safe to upgrade without much hassle. We have however experienced that this is not always the case. Major version updates (e.g. v3.0.0) require more investigating and testing to determine whether they are safe to upgrade, and may require code changes to be compatible. Experience has shown that updates to the Sanity Studio require more thorough testing than updates to the Next.js web project.

How to upgrade

Upgrades should ideally be handled individually. In some cases several can be done at once if they are related (for example all eslint related dependencies).

⚠ This includes committing upgrades individually/in relevant groups as this makes it easier to revert specific upgrades in case things don't work as they should after pushing to the repository.

Web & root

As stated above, patch and minor level updates should be safe to upgrade as they are not supposed to introduce breaking changes. These you can upgrade locally with the correct package manager and simply test the project to make sure everything is working correctly before committing.

For major updates the first order of business should be to find the changelog(s)/release notes and go through them to understand what the changes are and how they will affect our codebase. Once you understand what has been changed between our currently installed version and the latest version (note: there could have been multiple releases since we last upgraded) you can upgrade the dependency locally and begin testing.

Once you have upgraded you can test the code compatibility by running the following:

From the root of the repository:

  1. $ pnpm run lint will run eslint for both the root and web directory.
  2. $ pnpm web test will run the unit tests in the web directory.
  3. $ pnpm web build will attempt to build the Next.js application in the web directory, which includes a TS type check.

Sanity Studio

Experience has show that unfortunately even patch and minor level updates sometimes introduce breaking changes to our code. In addition to this, some updates may change the UI/UX of the Studio - in which case we need to inform the editorial team of these changes ahead of time.

It is therefor recommended to always read the changelog(s)/release notes for any Sanity related dependency updates before upgrading them. See the checklist for Sanity Studio upgrades on what to look for when testing the Studio.

Notes

The Sanity dependency @sanity/cross-dataset-duplicator is used in a separate Studio that only a select number of approved people have access to. Upgrades for this dependency should be handled by one of the approved developers.

Checklist for Sanity Studio upgrades

General

  1. Sanity Studio builds successfully
  2. Sanity Studio loads successfully
  3. Desk structure loads correctly
  4. Documents load correctly

Document interactions

Check this for each document type.

  1. Can open an existing document
  2. Can edit an existing document
  3. Can save and publish an existing document
  4. Can create and publish a new document
  5. Can delete an existing document
  6. Preview works correctly

Plugins

Internationalization plugin works correctly

  1. Can create new translation
  2. Can switch between translations
  3. Can delete both single translation and both at the same time

Media plugin works correctly

  1. Tab loads as expected
  2. Can open an asset in the Media plugin
  3. Can select assets from Media plugin in drop-down select in a document

Color list plugin works correctly

  1. Can create component with color list plugin (background color)
  2. Can change color
  3. Correct color renders in web

Webhooks

  1. Webhooks at https://www.sanity.io/manage ➡️ API ➡️ Webhooks work as expected

Checklist for web (Next.js app) upgrades

General

  1. No eslint errors
  2. Unit tests complete successfully
  3. No type errors
  4. Next.js app builds successfully
  5. Next.js app starts successfully

Pages

  1. Home page renders correctly.
  2. Topic pages render correctly (todo: add link to test page with all components).
  3. News articles render correctly.
  4. Magazine articles render correctly
  5. Menu renders and works correctly.

Algolia

Newsroom, magazine landing page, and search pages render correctly.

Check the following features:

  • Searching
  • Filtering
  • Pagination

Cookiebot

Cookiebot popup shows up and sets cookies correctly. If cookies are not accepted, the placeholder component should render correctly.

Language

The language toggle should work correctly.

Redirects

  1. Redirects defined in Sanity Studio work as expected
  2. Redirects defined in Next.js middleware work as expected
Clone this wiki locally