upgrade-best-practices.md

Upgrade best practices

This page explains what we (the Renovate maintainers) recommend you do to update your dependencies.

We'll cover starting a new project, updating a year-old project, and updating a project with five year old dependencies. We explain why you should update often, and how to nudge your team to update their dependencies.

General recommendations

In general, you should:

• Run Renovate on every repository
• Use the config:best-practices preset instead of config:recommended
• Use the Dependency Dashboard issue (it's on by default)
• Update your dependencies often
• Read the changelogs for the updates
• Update to new major versions in good time
• Talk with your team about the update strategy

If Renovate is too noisy for you, read the noise reduction docs.

Use the config:best-practices preset

The config:recommended preset is the recommended configuration for most Renovate users. Renovate also has a config:best-practices preset that includes our upgrade best practices.

You should extend from the config:best-practices preset:

{
  "extends": ["config:best-practices"]
}

If you're using config:recommended now, replace it with config:best-practices:

- "extends": ["config:recommended"]
+ "extends": ["config:best-practices"]

What's in the `config:best-practices preset?

The config:best-practices preset has this configuration:

{
  "configMigration": true,
  "extends": [
    "config:recommended",
    "docker:pinDigests",
    "helpers:pinGitHubActionDigests",
    ":pinDevDependencies"
  ]
}

The next sections explain each part of the preset.

Config migration

Renovate creates a config migration PR to replace old config option names with their new replacements. This way your configuration file and the Renovate docs always use the same terms.

You'll get config migration PRs no matter how you run Renovate: self-hosting or the Mend Renovate app.

Extends config:recommended

The config:recommended preset is a good base to start from. That's why we extend from it.

Extends docker:pinDigests

The Renovate docs, Docker Digest pinning section explains why you should pin your Docker containers to an exact digest.

Extends helpers:pinGitHubActionDigests

The GitHub Docs, using third-party actions recommend that you pin third-party GitHub Actions to a full-length commit SHA.

We recommend pinning all Actions. That's why the helpers:pinGitHubActionDigests preset pins all GitHub Actions.

For an in-depth explanation why you should pin your Github Actions, read the Palo Alto Networks blogpost about the GitHub Actions worm.

Extends :pinDevDependencies

Pinning your development dependencies means you, and your team, are using the same versions of development tools. This makes the developer-tool side of your builds reproducible. Debugging faulty versions of your tools is easier, because you can use Git to check out different versions of the tools.

Why updating often is easier, faster and safer

You may think that updating takes too much time. But updating regulary actually saves you time, because:

• Regular updates tend to be small
• Applying major updates is easier
• You'll be ready for CVE patches
• You'll look for ways to automate the updates

Regular updates tend to be small

Firstly, when you update regularly updates tend to be small. The update's changelogs are small, quick to read, and easy to understand. You probably only need to make changes in a few places (if at all) to merge the PR and get going again. Because you're reading the changelogs regularly, you'll get a feel for the direction of the upstream project.

Applying major updates is easier

Secondly, when you're current with upstream, major updates are easier. This is because you already:

• follow the latest best practices of upstream
• use the latest names for features/variables
• read the previous changelogs

You'll be ready for CVE patches

Thirdly, you'll be ready when a upstream package releases a patch for a critical CVE. If you're current, you can review and merge Renovate's PR quickly.

When you're behind on updates, you'll have a bad time, because you must read more changelogs and make more changes before you can merge the critical patch.

You'll look for ways to automate the updates

Finally, when you're updating often, you'll start looking for ways to automate the updates. You may start to automerge development dependencies like Prettier, or ESLint when the linter passes. Or you may decide to automerge any patch type upgrades, by using the default:automergePatch preset.

You may also start using GitHub's pull request merge queues to speed up the merge process. Renovate does not support GitLab's Merge Trains, see issue #5573.

Starting from a new project

Let's assume you're starting a new project. You created a new Git repository, installed the latest frameworks, libraries and development tools. After pushing the initial commit, you should enable and onboard Renovate.

Now you'll have to stay on the "update often" train.

Project with one year old dependencies

If you have a project that's a year behind on dependencies, you'll need to do some work. Let's assume that most dependencies need a patch or minor update, and at least one dependency needs a major update.

Start small, and get the patch and minor updates first. Read the changelogs for your updates. You may have to make small changes to get things working again.

When you have the latest patch and minor versions, you are ready for major updates. Start with major version updates for tools like Prettier or ESLint.

Then work on major updates for your framework or library. Take your time, read the changelogs, and make the necessary changes. Let multiple team members review your work before merging, it's easy to miss something.

Finally, update your development tools.

Now you're up to date, you should think how to make updating a regular habit.

Project with five year old dependencies

Let's assume your Dependency Dashboard lists more than 50 updates, and you have a few major version updates pending. If your project is this badly behind on updates, you have two problems:

• Updating your dependencies
• Improving your update process

Focus on critical updates first

Fix the easier problem first: getting back up to date. Update any dependencies that have critical updates for CVEs or other security related improvements.

If you're on the GitHub platform: follow the steps listed in the vulnerabilityAlerts docs to make sure Renovate is reading GitHub's Vulnerability Alerts.

You may want to enable the experimental osvVulnerabilityAlerts config option, to get OSV-based vulnerability alerts for direct dependencies. Read the osvVulnerabilityAlerts config option docs to learn more.

Fix blocking updates

Next, update any dependency that's blocking another update. You may need to update dependency A before you can update dependency B or C. In that case, update dependency A first.

Update to latest minor or patch of current version

Then update all dependencies to their latest minor or patch version, to prepare for the major updates.

Take major updates in sequence

Take major updates in sequence. This way you'll read the changelogs for each major version, and learn why upstream made certain breaking changes.

Say you're on version 1 of a dependency, and the latest major version is at 4. You should update to 2, then 3 and finally 4. Avoid updating from 1 directly to 4.

Use the :separateMultipleMajorReleases preset to get separate major updates.

Update development tools