iterative / iterative/cml

Add documentation links and helpful descriptions to error messages

Open
#606 3 comments 0 reactions 1 assignee Claimed by @0x2b3bfa0 View on GitHub
documentation epic technical-debt ui/ux
Dominant language
JavaScript
Stars
4.2k
Forks
345
PR merge metrics
No merged PRs in 30d

Description

## p1

The following have recently been documented in https://cml.dev/doc, but should also have better CLI errors pointing to said docs:

- [ ] #888
+ https://cml.dev/doc/ref/send-comment#GitHub
- [ ] #880
+ `uses: actions/checkout@v3, with.ref: ${{ github.event.pull_request.head.sha }}`
+ https://cml.dev/doc/usage?tab=GitHub
- [ ] #941
+ use default `GITHUB_TOKEN` or `GitHub App token`, not `Personal Access Token`
+ https://cml.dev/doc/ref/send-github-check
- [ ] #595
+ [ ] `Resource not accessible by integration`
+ [ ] `Error: Forbidden`
* "Ensure permissions are granted as per https://cml.dev/doc/self-hosted-runners?tab=GitLab#personal-access-token"?
- [ ] #911 (?)
- [x] #628
- [x] #563
- [x] #472
- [x] #813
- [x] #816
- [x] #835

## p2

- [ ] [#581/r656156462](https://github.com/iterative/cml/pull/581#discussion_r656156462): links like `https://err[or].cml.dev/YpQ` on errors that are especially tricky to explain inline or require additional context [...] e.g. https://error.dvc.org/no-dvc-cache
- [x] #1222 `cml CMD --help` links to `https://cml.dev/doc/ref/CMD`

## See also

- [#595/862336393](https://github.com/iterative/cml/issues/595#issuecomment-862336393): See #563 and [#563/r640709086](https://github.com/iterative/cml/pull/563#discussion_r640709086) for a good compromise between error message integrity and end user helpfulness.

```javascript
try {
operation();
} catch (error) {
if (error.message === 'Obscure error')
error.message += ', please try toggling the "more magic" switch';
throw error;
}
```

Contributor guide

No contributing guide indexed for this repository

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.