Docusaurus: Use a dependency management bot to deal with upgrades

[HonkingGoose]

💥 Proposal

I propose that this project uses a dependency management bot like Renovate or Depfu to get upgrades in a timely fashion.

Current situation

I know that this project already uses Dependabot to get security updates for the main Docusaurus dependencies which is fine, and a good thing to have.

The main development dependencies seem to get updated when needed.

However there's nothing keeping track of the boatload of dependencies in the packages directory at https://github.com/facebook/docusaurus/tree/master/packages.

It seem to me that all updates are manual as of now?
Updates seem to be done whenever somebody notices somethings out-of-date?

I think a bot will be way better at alerting you whenever there are upgrades to dependencies.
A bot will not forget, and will not get tired of watching for changes.

What a good dependency bot can do for you

A dependency bot helps to:

• Get a reminder about upgrades
• Get upgrades on a schedule that works for the project
• Get the kinds of upgrades that the project cares about (Major, major + minor, major + minor + patch)
• Get you to read the change-log for upgrades (the bot will show the change-log in the pull request)
• Keep abreast of dependency development direction via regularly reading the changelog for your dependencies

Benefits

• I think it will be easier to keep the dependencies up-to-date.
• You can configure the kind of upgrades you get from the bot
• If you have good test coverage upgrading can be quite easy (tests pass, read changelog, check changes made to package.json and yarn.lock, merge, done)
• The project will get updates on a regular schedule

Drawbacks

• Getting the bot configured just right will take some trial and error
• Somebody will have to check and merge the pull requests that the bot opens
• Even when the bot is configured just right, it might still note be a good fit for this project due to the amount of dependencies that are in the sub-directories of https://github.com/facebook/docusaurus/tree/master/packages
• Using a bot might not work well with the kind of release process you're using now
• Installing an app into this repository might be against this project's rules

Why I do not recommend the GitHub-native Dependabot

You might think, why doesn't HonkingGoose recommend Dependabot?
It's build into GitHub nowadays, so why not use that?

• You will get annoyed because you cannot tell Dependabot what kind of upgrades you care about.
• Dependabot will open multiple pull request to update separate things that really ought to be upgraded in one fell swoop.

Depfu/Renovate bots

I think a bot like Depfu or Renovate could be a good match for this project.

• Both bots are free to use for public repositories.
• Both bots support npm with yarn. Depfu only covers Ruby and JavaScript. Renovate covers more languages.
• Both of these bots are verified by GitHub.
• Both bots can bundle dependencies into one pull request, so that things that should only be upgraded as cohesive unit are upgraded all at once.
• Bot bots can be configured to only open pull requests for the patch level you want (Major versions only, major + minor versions, all versions)

Where to find these bots

Renovate on GitHub Marketplace
Depfu on GitHub Marketplace

Documentation for these bots

Renovate Docs
Depfu Docs

How to try out any of the bots

I strongly recommend you test out the bots on a fork first.
That way you can see how it works, and tinker with it before unleashing it on the main project.

Have you read the Contributing Guidelines on issues?

Yes.

I was not sure whether to use a feature request or a proposal. I think a proposal is closer to the scope of what would change for the project.

[HonkingGoose]

Hi @slorber, I noticed you got an offer from the creator of Renovate (@rarkins) to configure the Renovate bot exactly how you want.

I migrated from Dependabot to Renovate for all my repositories, and so far I'm really liking the bot and the team behind the bot. The team is really helpful whenever I have issues/questions, and the bot generally does the right thing by default (at least for my tastes). You have a boatload of options to configure Renovate just right, and now you have an expert to actually configure the bot just the way you want.

So I recommend you take the creator up on their offer to configure the bot for you. That way you'll get up and running quickly. I would of course have liked to be able to get you started with either Renovate or Depfu. But seeing as you can have an expert do it for you, I'm going to step out of the way here, and let the expert handle it. :+1:

[slorber]

Hi,

I'm not very familiar with the tool but already seen it used in some places.

Willing to try Renovabot to upgrade dependencies, and any help from you or @rarkins would great.
Will have to check with FB if it's ok to use this bot first.
I guess only a repo team member/admin can set it up right? (seems like I may have the permissions)

How complex is it to setup, and configure so that we don't end up being spammed by too many update PRs?

Generally if the deploy preview work then it should be fine, but we don't have good e2e tests yet, and not sure we want to bump dependencies each time a new version is published.

Does it make sense to receive upgrade PRs once a month, and also high-priority security upgrades?

[HonkingGoose]

TLDR:

• You need admin rights to install the app.
• You can tell the app what repositories it can check.
• You can reduce the noise by configuring Renovate so that it doesn't overwhelm you
• If you want I can set it loose on my fork of Docusaurus, so that you can see the onboarding pull request, and we can tinker with it there?
• Read the Renovate docs on reducing noise.
• Because Docusaurus is a big monorepo, ask @rarkins what works best for those, because I don't know how that should be configured.

I guess only a repo team member/admin can set it up right? (seems like I may have the permissions)

I think only admins can set up the Renovate bot on organization repositories. I think that Docusaurus falls under the Facebook organization.

You can try to install the app from the GitHub Marketplace (after you have approval from your boss), if you don't have the right permissions, it won't even work.
You can select which repositories to install the Renovate app on. So you can only enable Renovate for the Docusaurus project.

How complex is it to setup, and configure so that we don't end up being spammed by too many update PRs?

When you enable Renovate, the bot creates a on-boarding pull request, where it shows what would happen with the configuration you have then. You can edit that configuration setup branch, and then the pull request updates to show what just changed.

From the Renovate docs:

Conveniently, Renovate will not make any changes to your repository or raise any further Pull Requests until after you merge this initial Pull Request. So if there is anything about the Pull Request that you don't like or understand, take your time to read documentation or ask questions in one of our support forums and merge the PR only once you're satisfied with the result. You can edit your Renovate configuration within this renovate/configure branch and Renovate will keep updating the description in the PR to match, so you can keep doing that until you're satisfied with the results.

Generally, the first reaction people have to automated dependency updates like Renovate is "oh great/feel the power of automation". The next reaction a few days or weeks later is often "this is getting overwhelming". Indeed, if you leave Renovate on its default settings of raising a PR every single time any dependency receives any update.. you will get a lot of PRs and related notifications.

Renovate says these things are often changed:

• rangeStrategy: By default (with zero config) it's "replace" however the "config:base" preset overrides it to "auto". If you don't want to pin dependency versions and retain ranges, add the ":preserveSemverRanges" preset to the extends array.
• labels: Labels to assign to Pull Requests
• assignees: GitHub users to assign the Pull Requests to

I also think you will want to tinker with the schedule for Renovate, so that it only runs when you want it to run.

Now because this is a big monorepo, I'm sure configuring this right will take some help from the Renovate creator.
You basically have a lot of near duplicate package.json files, and I don't know what the best way to deal with those is, I've only ever used Renovate on simple repositories.

Renovate docs:

Getting started with Renovate with a GitHub marketplace app
About the onboarding pull request
Renovate docs on reducing noise

[rarkins]

Thank you @HonkingGoose! The above is great advice.

Renovate will always start with an "onboarding PR" which forecasts how many PRs are required, and lets you update the onboarding config in-PR and preview the results. But for maximum experimentation then installing it into a fork would be best for tuning it until you're ready for it on the main repo. You can see an example onboarding PR for my fork here.

Another way to approach things cautiously is to set "dependencyDashboardApproval": true. This will mean that no PRs are created by default after onboarding - just a mini dashboard issue that gives you control over which PRs to open. We use it in Renovate's own repo here although in our case we only require approval for major updates.

One of the features of monorepo support is that Renovate will update the same dependency across all packages at once, so that they don't get out of sync. Renovate can additionally support grouping:

• Which is essential because any packages you use from any other monorepo should be upgraded together
• Which is optional, because you want to group together e.g. non-major devDependencies so there's less overall PRs

Scheduling is also supported, e.g. weekly or monthly, which you can conveniently override to force creation any PR early via the dashboard if desired.

On ranges, the major decisions are:

• Should you pin dependencies to exact versions, for improved visibility in package.json?
• If you keep ranges in package.json, do you want Renovate updating the lock files every time there's a new version available? e.g. you have ^1.0.0 in package.json, 1.1.0 in yarn.lock and then 1.2.0 is released. Do you want a PR or not?

Projects which tend to use caret ranges (e.g. ^1.0.0) with lock files plus default Renovate configuration will generally find:

• Many dependencies in your lock file are "out of date" with patch or minor releases available
• Renovate will not have a reason to propose PRs other than major updates

If you prefer not to get individual PRs for ever non-major update then an alternative is to use Renovate's "lock file maintenance" feature. It essentially just wipes away your lock file and uses yarn to recreate it regularly, so that you are then up-to-date (within the constraints of your package.json ranges). Naturally if any of those non-major updates broke something then it's going to be tough to pinpoint if you've got hundreds of lines of diff in your yarn.lock.

[HonkingGoose]

Another way to approach things cautiously is to set "dependencyDashboardApproval": true.
This will mean that _no_ PRs are created by default after onboarding - just a mini dashboard issue that gives you control over which PRs to open.

I like the dashboard idea! That way the maintainer can pull the updates on a schedule convenient for them.
I also like the dashboard because then you have easy visibility on what you're doing with the bot.
It also prevents slorber from getting flooded with pull request the minute he turns the bot on.

Scheduling is also supported, e.g. weekly or monthly, which you can conveniently override to force creation any PR early via the dashboard if desired.

Dang, that's really handy! :+1: You can say: "leave me alone Renovate bot, only bother me on Mondays" (for example), but if you want updates earlier than the schedule you can request them from the bot via the dashboard. I hadn't thought of that workflow yet!

One of the features of monorepo support is that Renovate will update the same dependency across all packages at once, so that they don't get out of sync.

Does this mean that Renovate deals with the current https://github.com/facebook/docusaurus/tree/master/packages system setup by default? I'm not not sure how much manual configuration you need to update all those package.json files in each packages sub-directories?

[HonkingGoose]

I've looked at the on-boarding pull request on @rarkins's fork of Docusuarus.
Renovate sure would open a lot of pull requests (51), that's way too much for any maintainer to deal with at once.
We need to prevent flooding the maintainer with all those pull requests.

Maybe it's a good idea to ask @slorber how they want the bot to work.
Then you/we can configure Renovate on the fork according to their specifications, and then let it run on the fork, so that @slorber can see how the bot works.

I think these questions are good starters to cover the basic functionality and workflow:

• What schedule do you want Renovate to run on?
• Do you want labels for the pull requests?
• Do you want the pull requests assigned to a specific person?
• Do you want to use the Renovate bot dashboard?
• What kind of rangeStrategy do you want to use?
• Do you want to auto-merge certain dependencies or certain types of dependencies?
• Do you want to group certain dependency types into one pull (say all linters in one pull, for example)?
• Should you pin dependencies to exact versions, for improved visibility in package.json?
• If you keep ranges in package.json, do you want Renovate updating the lock files every time there's a new version available? e.g. you have ^1.0.0 in package.json, 1.1.0 in yarn.lock and then 1.2.0 is released. Do you want a PR or not?
• How do you want to deal with yarn.lock file maintenance?

[rarkins]

Does this mean that Renovate deals with the current https://github.com/facebook/docusaurus/tree/master/packages system setup by default?

Yes

Renovate sure would open a lot of pull requests (51), that's way too much for any maintainer to deal with at once.

FYI default behavior is maximum 2 per hour and 20 concurrently, and both of those are configurable.

Ultimately, there's a lot of out-of-date dependencies here, even when most non-major updates are being ignored from that calculation (it's mostly major). I would say you might want to keep ranges as-is until there's less to upgrade, but maybe to monthly lock file maintenance to keep locked versions updated to latest in range.

There appears to be some grouping that could be done (e.g. react-based, or remark-based, etc) although major updates for related packages aren't necessarily dependent on each other and if you get breaking changes from more than one package at a time then it can be challenging to figure out exactly why. If you're lucky, many major updates in JS packages are simply to bump the minimum supported Node.js version, which means zero work/changes required.

[slorber]

Hi and thanks for the infos.

My Facebook manager is ok to install such a bot, and I confirm I don't have permissions to do so myself.

The dashboard looks nice.

Please note that we have docusaurus-1 and docusaurus-2 on the same repo.
Docusaurus 1 might use outdated dependencies, but we don't specifically want to upgrade them unless there's a strong reason to do so (website-1.x + packages/docusaurus-1.x). We'll maybe move these to a separate v1 branch after v2 is officially released.

What I notice in the fork PR is that Renovabot suggests me to upgrade to Webpack 5, Remark 13, React 17... etc. Those look like major upgrades to me. I don't particularly expect a bot to handle them for me 😅

Our plan is not particularly to be early adopters of new major version releases. I'd rather wait for community feedback than upgrading deps as soon as they get published.

What schedule do you want Renovate to run on?

Once per month to start, and maybe more if this is sustainable?
But I don't either want Renovabot to open me 50 PRs, every month ^^
I prefer to start slowly adopting this tool.
1 PR per month upgrading all semver compatible dependencies is better than current state.

Do you want labels for the pull requests?

Why not

Do you want the pull requests assigned to a specific person?

No

Do you want to use the Renovate bot dashboard?

Yes

What kind of rangeStrategy do you want to use?

Keem semver ranges, don't lock users on a specific version

Do you want to auto-merge certain dependencies or certain types of dependencies?

No

Do you want to group certain dependency types into one pull (say all linters in one pull, for example)?

Yes, I'm ok to upgrade dev tools in a more automated fashion than user runtime code.

Should you pin dependencies to exact versions, for improved visibility in package.json?

I guess it depends, but by default I'd say no

If you keep ranges in package.json, do you want Renovate updating the lock files every time there's a new version available? e.g. you have ^1.0.0 in package.json, 1.1.0 in yarn.lock and then 1.2.0 is released. Do you want a PR or not?
How do you want to deal with yarn.lock file maintenance?

I'm ok to receive such PR as long as it's like once a month or so.

---

Not sure about the details and what is possible but:

• I don't want PRs for docusaurus 1 code (unless security...)
• I don't want to receive a PR to upgrade Webpack 4 to Webpack 5, React 16 to React 17 etc...
• I don't want to upgrade the semver ranges in package.json files,
• I'm ok for dashboard a suggestion to upgrade from Webpack 4 to Webpack 5 and other semver incompatible version upgrades
• I'm ok for upgrading semver compatible versions through lockfile, and receive suggestions for semver incompatible changes through the dashboard (but don't want to update package.json files, keep the semver range)
• I'm ok for immediate PRs targeting high priority security issues
• I'm ok for delayed PRs for semver incompatible upgrades targeting dev tools like Prettier, ESLint, Husky, Lint-staged...

Does it make sense?

[HonkingGoose]

Yes this make sense! We now have some general requirements to configure the bot the right way.

I propose we take @rarkins up on his offer to configure the bot for this project. He knows the ins and out of the bot and how to configure it to your wishes.

[HonkingGoose]

Hi @slorber 👋

@rarkins and I made a config for you to review.

We tried to stick as closely as possible to your requirements. I think you'll be very happy with this bot.

You can take a look at the Renovate bot running on the rarkins/docusaurus fork here: https://github.com/rarkins/docusaurus/issues/5

Greetings HonkingGoose

[slorber]

Thanks @HonkingGoose @rarkins , that looks nice.

I think we can probably give it a try and see if it works well for our use-case, not sure I'll be able to give more feedback without setting this up 🤪

Will see soon how to get it installed, as I don't think I am able to install an app on this repo