facebook / facebook/docusaurus

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

Offen
#9,714 2 Kommentare 0 Reaktionen 0 zugewiesene Personen Auf GitHub ansehen
proposal status: needs triage
Vorherrschende Sprache
TypeScript
Sterne
66.2k
Forks
10k
Ø Merge
1 T. 3 Std.
Gemergte PRs (30 T.)
52

Beschreibung

### Have you read the Contributing Guidelines on issues?

- [X] I have read the [Contributing Guidelines on issues](https://github.com/facebook/docusaurus/blob/main/CONTRIBUTING.md#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.**

```tsx
/**
* 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.**

```tsx
/**
* 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

- [X] I'd be willing to do some initial work on this proposal myself.

Beitragsleitfaden

Beitragsleitfaden öffnen

Bewertung

Dieses Issue wurde noch nicht bewertet.

Neue Issues direkt in Ihr Postfach

Eine kurze Übersicht über anfängerfreundliche GitHub-Issues.