facebook / facebook/docusaurus

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

未关闭
#9,714 2 条评论 0 个 reaction 已指派 0 人 在 GitHub 查看
proposal status: needs triage
主要语言
TypeScript
星标
66.2k
派生
10k
平均合并
1 天 3 小时
30 天内合并 PR
52

描述

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

贡献指南

打开贡献指南

评估

这个 Issue 还没有评估数据。

把新 issue 发到你的邮箱

精选适合新手参与的 GitHub issue 摘要。