Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

docs: explained rule fixers and suggestions #17657

Merged
merged 3 commits into from Oct 24, 2023
Merged

docs: explained rule fixers and suggestions #17657

Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
bce4ce7
docs: explained report fixers and suggestions
JoshuaKGoldberg Oct 17, 2023
1672191
Apply suggestions from code review
JoshuaKGoldberg Oct 17, 2023
ea27096
Post-suggestion fix: rule-categories.macro.html link
JoshuaKGoldberg Oct 17, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
2 changes: 1 addition & 1 deletion docs/src/_includes/components/rule-categories.macro.html
View file
Open in desktop
Expand Up @@ -21,7 +21,7 @@
<div class="rule-category">
<span class="rule-category__icon">💡 <span class="visually-hidden">hasSuggestions</span></span>
<p class="rule-category__description">
Some problems reported by this rule are manually fixable by editor <a href="../extend/custom-rules#providing-suggestions">suggestions</a>
Some problems reported by this rule are manually fixable by editor <a href="../use/core-concepts#report-suggestions">suggestions</a>
</p>
</div>
{%- endif -%}
Expand Down
17 changes: 17 additions & 0 deletions docs/src/use/core-concepts.md
View file
Open in desktop
Expand Up @@ -23,6 +23,23 @@ ESLint contains hundreds of built-in rules that you can use. You can also create

For more information, refer to [Rules](../rules/).

### Rule Fixes

Rules may optionally provide fixes for violations that they find. Fixes safely correct the violation without changing application logic.
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

#17657 (review):

I've started to use the term "violations" to describe lint errors -- we have too many other words floating around in the docs right now, so definitely room to improve.

Interesting! Are there any other discussion places that come to mind for the consolidation? I can file an issue if not. IMO it'd be valuable to have shared vocab used as a standard in the docs. Even a glossary long-term.

In case it's useful: "violation" is not what I personally would lean towards right now. It's a bit more intense and opinionated of a word than "report".

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nothing official, no. Just something I've been thinking about. A glossary is definitely of interest to me.

Our problem is that we already have clearly defined meanings for several terms that we could use:

  1. problem - Type of rule
  2. suggestion - Actually both a type of rule and an unsafe fix (need to disambiguate this in the future)
  3. error - Too ambiguous vs. runtime errors and also a severity level
  4. warning - Severity level

We've actually used "report" historically to represent the collection of violations for a given run, so I'm not in favor of repurposing that.

Thinking in terms of rule violations make sense to me, which is why I started adopting "violation" as the term. Definitely open to other suggestions.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Realized I never back-linked: #17987 tracks adding a glossary.


Fixes may be applied automatically with the [`--fix` command line option](https://eslint.org/docs/latest/use/command-line-interface#--fix) and via editor extensions.

Rules that may provide fixes are marked with 🔧 in [Rules](../rules/).

### Rule Suggestions

Rules may optionally provide suggestions in addition to or instead of providing fixes. Suggestions differ from fixes in two ways:

1. Suggestions may change application logic and so cannot be automatically applied.
1. Suggestions cannot be applied through the ESLint CLI and are only available through editor integrations.

Rules that may provide suggestions are marked with 💡 in [Rules](../rules/).

## Configuration Files

An ESLint configuration file is a place where you put the configuration for ESLint in your project. You can include built-in rules, how you want them enforced, plugins with custom rules, shareable configurations, which files you want rules to apply to, and more.
Expand Down