facebook / facebook/docusaurus

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

Abierto
#9,714 2 comentarios 0 reacciones 0 asignados Ver en GitHub
proposal status: needs triage
Lenguaje dominante
TypeScript
Estrellas
66.2k
Forks
10k
Merge medio
1 d 3 h
PR fusionados (30 d)
52

Descripción

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

Guía de contribución

Abrir la guía de contribución

Evaluación

Este issue todavía no se ha evaluado.

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.