docs: ensure "learn more" deprecation links point to useful resource #19590
Conversation
✅ Deploy Preview for docs-eslint canceled.
|
This reverts commit e6d0c70.
|
I'm not sure exactly how the website generated files are supposed to work. Running |
The command you need to use is |
|
@amareshsm Ah, great, thanks! It looks like there's a few unrelated changes in the rules_meta file, I'm guessing this just didn't synced in a previous commit. |
lib/rules/no-return-await.js
Outdated
| message: | ||
| "The original assumption of the rule no longer holds true because of engine optimization.", | ||
| url: "https://eslint.org/docs/latest/rules/no-return-await", | ||
| url: "https://github.com/eslint/eslint/issues/17345", |
There was a problem hiding this comment.
This was a link to the docs page for this rule because the explanation of the deprecation is on that page. It just looks weird when the URL is used from the page itself. Maybe we could add logic to hide the "Learn more" link in these cases?
(the same for prefer-reflect).
There was a problem hiding this comment.
Slight pushback - personally, the reason I clicked the "learn more" link is exactly because I was looking for the deprecation issue (#17345), which contains much more info than the the rule page. So I find the deprecation issue quite a bit more useful than no link to "learn more" at.
But I'll look into the hiding the link unless I hear otherwise.
There was a problem hiding this comment.
I think most people would prefer to see a summary rather than search through the issue discussions to understand the reasons. Perhaps we could add a link to the issue on the rule page? (and keep this URL and hide "Learn more").
@nzakas what do you think?
There was a problem hiding this comment.
Is the deprecation url used somewhere other than the rule page?
There was a problem hiding this comment.
Is the deprecation url used somewhere other than the rule page?
I believe we're not using it anywhere else in eslint, but since it's in rule meta, it can be used in other tools (e.g., IDEs).
There was a problem hiding this comment.
Ok. For now implemented it such that the link is optional... I'd think if tooling consumes it, they can reasonably default it with deprecated.url ?? docs.url.
There was a problem hiding this comment.
I'm not sure people care why a rule was deprecated in most cases. If there's a notable reason why it was deprecated then I think that should go directly into the documentation page. In either case, "Learn More" isn't needed.
There was a problem hiding this comment.
Just to be sure we're aligned, is the solution of omitting deprecated.url satisfactory, or is there a different action requested?
Co-authored-by: Francesco Trotta <[email protected]>
Prerequisites checklist
What is the purpose of this pull request? (put an "X" next to an item)
[x] Documentation update
[ ] Bug fix (template)
[ ] New rule (template)
[ ] Changes an existing rule (template)
[ ] Add autofix to a rule
[ ] Add a CLI option
[ ] Add something to the core
[ ] Other, please explain:
fixes #19589
It looks like these deprecation links were introduced in #19238.
For thoroughness, I looked through all of the deprecation URLs, and noticed that prefer-reflect had the same problem, so I changed that is well, but the rest looked good.