ember-cli / ember-cli/ember-cli-update

Improve failure messaging for missing ember-cli versions

Đang mở
#818 4 bình luận 1 reaction 0 người được giao Xem trên GitHub
Ngôn ngữ chính
JavaScript
Star
279
Fork
44
Chỉ số merge pull request
Không có pull request nào được merge trong 30 ngày

Mô tả

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.

Hướng dẫn đóng góp

Chưa lập chỉ mục được hướng dẫn đóng góp cho kho mã nguồn này

Hướng nghiên cứu

Bắt đầu bằng cách theo dõi cách CLI xử lý tham số --to và phân giải các phiên bản ember-cli đối chiếu với ember-new-output. Xem lại các đường dẫn lỗi hiện tại khi thiếu bản phát hành và các quy ước đầu ra hiện có. Công việc được xem là hoàn tất khi phạm vi đã được thống nhất và có các bài kiểm thử cho lỗi xác thực, phần tóm tắt phiên bản và các phương án thay thế được đề xuất; issue không nêu tên tệp hay bài kiểm thử.

Do mô hình lập chỉ mục viết ra từ nội dung của issue.

Đánh giá

Công nghệ
javascript
Lĩnh vực
cli
Loại issue
Tính năng
Độ khó
5/5
Thời gian dự kiến
Hơn một tuần
Mức độ hoạt động
Đình trệ
Độ rõ ràng
Cần làm rõ
Mức phù hợp với người mới
25/100

Nhận issue mới trong hộp thư của bạn

Bản tóm tắt ngắn những issue GitHub phù hợp với người mới.