Proposal: prevent @docusaurus package version mismatches

[slorber]

💥 Proposal

As seen here: #3363

If you have some @docusaurus/* packages on alpha 61, and some on alpha 62, the site might not work correctly.

Sometimes users try to upgrade but one dep is left to an older version, and we have cryptic error messages at dev/build time.

We should prevent running a Docusaurus site if the @Docusaurus packages do not have the exact same version, with a proper error message.

Note: dependabot and other deps upgrade bots will submit PRs to repos asking you to upgrade doccusaurus packages one at a time, so all these PRs should fai on purpose. We should upgrade Docusaurus deps all at once, in a single PR.

[TomBrien]

Note: dependabot and other deps upgrade bots will submit PRs to repos asking you to upgrade doccusaurus packages one at a time, so all these PRs should fai on purpose. We should upgrade Docusaurus deps all at once, in a single PR.

I believe (although not tested) a solution to this is packages outside of @docusaurus/core makings sure the peerDependency is pinned to a particular version. This should ensure dependabot and friends realise the two packages need updating in one PR rather than allowing them to update independently. E.g. for preset-core-classic:

  "peerDependencies": {
-   "@docusaurus/core": "^2.0.0",
+   "@docusaurus/core": "2.0.0-alpha62",
    "react": "^16.8.4",
    "react-dom": "^16.8.4"
  },

[slorber]

Yes, we should do that for all ^2.0.0 refs.

The problem is also that Lerna publish does seem to add back the ^ on every publish, so even if we prevent users from using an older deps, we should also ensure that they don't get a newer version that mismatch with the others (ie all at alpha 62 except one at alpha 63)

I think a runtime check would be more reliable.

We had this idea of "docusaurus doctor", that can also be part of it (#2267), but if it's not too expensive I think it could run on each start/build

[slorber]

Should be fixed by #3386