facebook / facebook/docusaurus

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

Ouverte
#9,714 2 commentaires 0 réactions 0 personnes assignées Voir sur GitHub
proposal status: needs triage
Langage dominant
TypeScript
Étoiles
66.2k
Forks
10k
Merge moyen
1 j 3 h
PR mergées (30 j)
52

Description

### 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.

Guide de contribution

Ouvrir le guide de contribution

Évaluation

Cette issue n'a pas encore été évaluée.

Recevez les nouvelles issues par e-mail

Un résumé court des issues GitHub adaptées aux débutants.