ember-cli
Improve failure messaging for missing ember-cli versions
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
--toparam, 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
[email protected] has not been released
# For an ember-cli version without a corresponding ember-new-output release
$ ember-cli-update --to 3.12.1
[email protected] 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
[email protected] has not been released. Did you mean [email protected]?
# for a missing major or minor versions (edge case)
$ ember-cli-update --to 3.16
[email protected] has not been released. Did you mean [email protected]?
$ ember-cli-update --to 4
[email protected] has not been released. Did you mean [email protected]?
Alternatively, we could provide a list of options, though I think the context is specific enough to just give the latest.
Those are some good ideas. Regarding this message:
[email protected] 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.
We will probably want to put some sort of hour timer on it. The ember-cli release process can take an hour or so if there are issues, and some people are ready to update as soon as it reaches npm, but the output repo may not be ready yet. Giving them a message to open an issue, before it is an actual issue yet, would not be necessary.
Regarding
This will also update to:
- ember-source@~3.12.0
- ember-data@~3.12.0
That might be overkill. The tool doesn't even know about those versions. Are you aware of ember-cli-update --compare-versions? That would show you what is changing, including ember versions.
@kellyselden thanks for the comments.
I was not aware of --compare-versions, I'll have a play with it. It sounds like it'll cover that portion of our problem.
I'll get a PR going that covers the basic idea - providing feedback when targeting a non-existent release of ember-cli.
Then, I can look at a follow-up PR, or some different messaging, that explain the ember-new-output issue.
We could potentially cover the release delay use case by looking at timestamps, though perhaps that's overcomplicated. We could keep the has no corresponding release message, for example, but avoid asking to open an issue, and to mention the release delay as a factor.
I got something similar to this when my current version of ember-source was an s3 file:
"ember-source": "https://s3.amazonaws.com/builds.emberjs.com/canary/shas/8438cd59062d38d0624b8c07187ecc91fe78ad91.tgz",
Got this error:
λ ember-cli-update
{ Error: Command failed: git --git-dir="C:\Users\Alon\AppData\Local\Temp\tmp-296243779daiha709\.git" rev-parse vnull
fatal: ambiguous argument 'vnull': unknown revision or path not in the working tree.
Use '--' to separate paths from revisions, like this:
'git <command> [<revision>...] -- [<file>...]'
at ChildProcess.exithandler (child_process.js:294:12)
at ChildProcess.emit (events.js:198:13)
at maybeClose (internal/child_process.js:982:16)
at Process.ChildProcess._handle.onexit (internal/child_process.js:259:5)
killed: false,
code: 128,
signal: null,
cmd:
'git --git-dir="C:\\Users\\Alon\\AppData\\Local\\Temp\\tmp-296243779daiha709\\.git" rev-parse vnull',
stdout: 'vnull\n',
stderr:
'fatal: ambiguous argument \'vnull\': unknown revision or path not in the working tree.\nUse \'--\' to separate paths from revisions, like this:\n\'git <command> [<revision>...] -- [<file>...]\'\n' }
