renovatebot_renovate/docs/usage/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 blog post 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 regularly 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

Finally update development tools like Prettier, ESLint, TSLint, Cypress, and so on.

Improve the human side

You're done with the technical side. Now comes the harder part, fixing the human side. There are probably a number of reasons why the project got this badly out of date.

When working on the human side, focus on the process, rules, and habits. Avoid blaming developers for not updating often.

Why developers avoid updating

Let's assume most developers want a project that's up to date. So why are your developers avoiding updates? Some common reasons:

• Developers get blamed when things break in production
• There are no tests, so merging updates is scary
• The test suite is slow
• Releasing a new version of the project must be done by hand
• Updating must be done by hand
• The company doesn't allow developer time for updates
• The company has complex rules about updates

If updating is painful, or takes a lot of time, developers tend to avoid it. Make it easy and fast to update dependencies.

Talk with your team about the update process

Listen to your team, write down their problems. Then fix each problem as best as you can.

Make updating easy and fast

Respect your developer's time and brains:

• Run Renovate on all projects
• Use Renovate to propose updates
• Building the project must be as fast as possible
• Have automated tests for the critical path of your project
• Run the automated tests on every pull request
• If you're on GitHub: use GitHub's Merge Queue to speed up merges
• Follow SemVer versioning
• Use the semantic-release bot to automate the release process
• Refactor existing code to make future changes easier

Ground rules

As a starting point:

• Avoid long lived branches that diverge from main over time
• Dig beyond "developer error" when things go wrong, again: focus on the process
• Ensure company policy allows frequent updates

How we use Renovate

• We run Renovate on all repositories
• Most of our repositories have automated tests for the critical path of the application
• We automerge some dependencies, but request major updates from the Dependency Dashboard
• When a developer merges a breaking change, we revert to a known-good version, and try again later
• We automated the release with the semantic-release bot
• We spend time to make our build and automated tests as fast as possible

How others use Renovate

Read the Swissquote user story to see how they use Renovate.

Recommended reading

There's a lot of good information out there, so we can only highlight a few resources.

Martin Fowler has two great resources:

• The free page Patterns for Managing Source Code Branches to help you decide what Git branch pattern to use
• The book Refactoring, Improving the Design of Existing Code to help your developers gradually refactor to clean, modular and easy to read code

The git bisect command can help you find out which commit introduced a bug, or other behavior change. Read the ProGit 2 book, section on binary search to learn more.