ember-cli / ember-cli/ember-cli-update
Improve failure messaging for missing ember-cli versions
- 主要语言
- JavaScript
- 星标
- 279
- 派生
- 44
- PR 合并指标
- 30 天内没有已合并 PR
描述
We recently had some confusion when attempting to upgrade to Ember 3.12.2, and I'd like to propose some improved failure messaging to guide devs in these circumstances.
The primary issue is that `ember-cli-update` won't fail when given a non-existent ember-cli version as a target, via the `--to` param. Instead, we found it could either:
- ignore the `--to` param, silently change the target to `*`, and upgrade to the latest instead (3.14 in our case), or
- crash out with a git error if the ember-cli version doesn't exist, with output `fatal: ambiguous argument 'v3.12.1': unknown revision or path not in the working tree.`
I'd like to propose a few improvements to the developer experience, in terms of failure messaging around ember-cli-versions.
**1. Validate the target version**
When a dev targets an ember-cli version, we could validate that the version exists, and has a corresponding release in `ember-new-output`. If not, we could exit and display a message to indicate the reason for the validation failure,
This would avoid unexpected results by silently using a surprising default, or by hitting a `fatal: ambiguous argument` git error when the `ember-new-output` release is missing.
If it's a case of a missing `ember-new-output` release, we might even provide an action (like a link to open an issue in a repo, or to post in Discord) to rectify the problem.
Examples
```
# For non-existent ember-cli version
$ ember-cli-update --to 3.12.2
ember-cli@3.12.2 has not been released
# For an ember-cli version without a corresponding ember-new-output release
$ ember-cli-update --to 3.12.1
ember-cli@3.12.1 has been released, but has no corresponding release in ember-new-output. Please file an issue at https://github.com/ember-cli/ember-cli/issues.
```
**2. Display a version change summary**
When first running `ember-cli-update`, we could print a summary of the versions changes of the major Ember packages that would occur, like:
```
$ ember-cli-update --to 3.12.0
Updating to ember-cli@~3.12.0
This will also update to:
- ember-source@~3.12.0
- ember-data@~3.12.0
```
I'm not 100% on the style of this output. Nonetheless, it aims to alleviate the confusion we hit around which package we're targeting. We thought `--to 3.12.2` was targeting `ember-source` at first, and some improved messaging along these lines may help.
**3. Show alternative versions when the target version is missing**
This would be an enhancement to idea 1.
If the dev targets an `ember-cli` version that is unreleased, they're given a "did you mean" message with the latest version, relative to their target. We'd find this useful when accidentely targeting a patch release that doesn't exist.
It's also a potential avenue to head off confusion over which package is being targeted (`ember-cli` or `ember-source`), by making it explicit in the failure message.
```
# for a missing patch version (main use case)
$ ember-cli-update --to 3.12.2
ember-cli@3.12.2 has not been released. Did you mean ember-cli@3.12.1?
# for a missing major or minor versions (edge case)
$ ember-cli-update --to 3.16
ember-cli@3.16.0 has not been released. Did you mean ember-cli@3.14.0?
$ ember-cli-update --to 4
ember-cli@4.0.0 has not been released. Did you mean ember-cli@3.14.0?
```
Alternatively, we could provide a list of options, though I think the context is specific enough to just give the latest.
贡献指南
这个仓库没有索引到贡献指南
调研方向
首先追踪 CLI 如何处理 --to 参数,以及如何根据 ember-new-output 解析 ember-cli 版本。检查缺少发布版本时当前的错误路径以及现有的输出约定。完成的标准是范围达成一致,并为验证错误、版本摘要和建议的替代方案编写测试;该 issue 未指定文件或测试。
由索引模型根据 Issue 内容生成。
评估
- 技术栈
- javascript
- 领域
- cli
- Issue 类型
- 功能
- 难度
- 5/5
- 预计耗时
- 一周以上
- 活跃度
- 停滞
- 描述清晰度
- 需要澄清
- 新手友好度
- 25/100