ember-cli / ember-cli/ember-cli-update
Improve failure messaging for missing ember-cli versions
- Dominant language
- JavaScript
- Stars
- 279
- Forks
- 44
- PR merge metrics
- No merged PRs in 30d
Description
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.
Contributor guide
No contributing guide indexed for this repository
Assessment
This issue has not been assessed yet.