Warn on major version changes when displaying the cli upgrade message.

[homotechsual]

Have you read the Contributing Guidelines on issues?

• I have read the Contributing Guidelines on issues.

Motivation

Currently we surface upgrades in the CLI when running any docusaurus CLI command with either an npm or yarn example invocation. We do this regardless of the version change - so if you're on 2.4.3 you'll get shown commands to upgrade to 3.1.0 (at the time of writing!)

I'm proposing we do one of two things:

Option 1: Suppress the upgrade message on a major version upgrade.

  /**
   * We don't want to display update message for major version upgrades or canary releases.
   * See https://github.com/facebook/docusaurus/issues/
   * @param {import('update-notifier').UpdateInfo} update
   */
  function ignoreUpdate(update) {
    const isCanaryRelease = update?.current?.startsWith('0.0.0');
    const isMajorRelease = update?.type? === "major"
    if (isCanaryRelease || isMajorRelease) {
      return true
    } else {
      return false
    }
  }

This has at least one major drawback which is it would essentially hide all knowledge of any update when a major version increment happens.

Option 2: Display a warning message when the update is a major version.

  /**
   * Show a warning message when the version update is a major version.
   * See https://github.com/facebook/docusaurus/issues/
   * @param {import('update-notifier').UpdateInfo} update
   */
  function getUpgradeWarnings(update) {
    const isMajorRelease = update?.type? === "major"
    if (isMajorRelease) {
      return `This update is a major version. Check the release announcement on https://docusaurus.io for upgrade steps. It is not advised to upgrade using the command provided unless you know what you are doing.`
    }
  }

This would seem to be the safer option - maintains visibility of the updates but makes it clear that there are likely extra steps.

Self-service

• I'd be willing to do some initial work on this proposal myself.

[homotechsual]

Third option I thought of after posting - replace the entire message if there's a major change to just say to check the release announcements rather than say check those and still display the command.

[slorber]

Makes sense 👍

I would go with the 2) option and showing a different message for major versions.

We shouldn't print the upgrade command in this case and just ask user to check the major version blog post instead.