docs: Core concepts page #16399

bpmutter · 2022-10-08T21:49:44Z

Prerequisites checklist

I have read the contributing guidelines.

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:

What changes did you make? (Give an overview)

Add a page to the user guide about the core concepts of ESLint.

The page contains minimalistic explanations, with links out to the more detailed explanation pages.

Is there anything you'd like reviewers to focus on?

I intentionally kept this page pretty minimalist. Specifically, I didn't include any code examples. I decided not to include code examples to really keep this page focused on the concepts (pure explanation using the Divio framework). I'm not 100% convinced this is the correct decision, and look forward to the reviewers' thoughts and feedback on the matter.

Fixes #16382

netlify · 2022-10-08T21:50:00Z

✅ Deploy Preview for docs-eslint ready!

Name	Link
🔨 Latest commit	`4832f3a`
🔍 Latest deploy log	https://app.netlify.com/sites/docs-eslint/deploys/6350a905ea2aca000841b411
😎 Deploy Preview	https://deploy-preview-16399--docs-eslint.netlify.app/user-guide/core-concepts
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify site settings.

nzakas

Thanks for putting this together! I left some small notes throughout.

I think there are probably some other core concepts that would be worth adding to this page:

Shareable configs - this is the largest part of the ESLint ecosystem, so I think it makes sense to mention this after configuration files.
Parsers - many folks use alternate parsers to help ESLint parse different syntax. typescript-eslint (for TypeScript syntax) and @babel/eslint-parser (for experimental syntax) are examples.
Processors - allow ESLint to parse JS out of another file. For example eslint-plugin-markdown allows ESLint to pull JS code out of Markdown files and lint it.

docs/src/user-guide/core-concepts.md

nzakas · 2022-10-13T19:42:20Z

docs/src/user-guide/core-concepts.md

+
+## Plugins
+
+An ESLint plugin is an npm module that contains a set of ESLint rules.


Plugins can contain rules, configurations, processors, and environments.

docs/src/user-guide/core-concepts.md

nzakas · 2022-10-14T17:44:35Z

I just noticed - it appears that your editor may be adding in hard line breaks after a certain number of characters on each line. Can you adjust that so those hard line breaks don't appear? At least in my editor, this isn't the default, so it's a bit harder for me to make changes because the line breaks move around as the content changes.

Co-authored-by: Nicholas C. Zakas <nicholas@humanwhocodes.com>

bpmutter · 2022-10-18T02:05:18Z

I just noticed - it appears that your editor may be adding in hard line breaks after a certain number of characters on each line. Can you adjust that so those hard line breaks don't appear? At least in my editor, this isn't the default, so it's a bit harder for me to make changes because the line breaks move around as the content changes.

as a personal practice i break lines (by hitting enter manually) around 80 characters. this lets you have a more specific commit history and looks better if the editor doesn't have word wrapping.

but will refactor to stick by this projects conventions and make 1 paragraph == 1 line

bpmutter · 2022-10-18T02:16:16Z

@nzakas implemented all your feedback. please take another look when you get the chance!

nzakas

Nice, this is looking really good. I just left a couple of small comments and then we should be good to go.

nzakas · 2022-10-19T23:08:24Z

docs/.vscode/settings.json

@@ -0,0 +1,3 @@
+{
+  "editor.formatOnType": false
+}


We aren’t typically including vscode settings file. Was this included by mistake?

yep, will remove!

nzakas · 2022-10-19T23:10:27Z

docs/src/user-guide/core-concepts.md


 For more information, refer to [Configuring Plugins](./configuring/plugins.md).

+## Parsers
+
+An ESLint parser converts code into an abstract syntax tree that ESLint can evaluate. By default, ESLint uses a built-in parser that is compatible with standard JavaScript runtimes and versions.


Might be worth mentioning the default parser is Espree and link to the eslint/espree repo in this paragraph.

absolutely, didn't know it had a dedicated name. will add.

docs/src/user-guide/core-concepts.md

Co-authored-by: Nicholas C. Zakas <nicholas@humanwhocodes.com>

bpmutter · 2022-10-20T01:49:53Z

@nzakas implemented your feedback. ready for re-review

nzakas

Awesome! Very excited to get this out. Thanks so much.

This PR contains the following updates: | Package | Type | Update | Change | |---|---|---|---| | [eslint](https://eslint.org) ([source](https://github.com/eslint/eslint)) | devDependencies | minor | [`8.25.0` -> `8.26.0`](https://renovatebot.com/diffs/npm/eslint/8.25.0/8.26.0) | --- ### Release Notes <details> <summary>eslint/eslint</summary> ### [`v8.26.0`](https://github.com/eslint/eslint/releases/tag/v8.26.0) [Compare Source](eslint/eslint@v8.25.0...v8.26.0) #### Features - [`4715787`](eslint/eslint@4715787) feat: check `Object.create()` in getter-return ([#16420](eslint/eslint#16420)) (Yuki Hirasawa) - [`28d1902`](eslint/eslint@28d1902) feat: `no-implicit-globals` supports `exported` block comment ([#16343](eslint/eslint#16343)) (Sosuke Suzuki) - [`e940be7`](eslint/eslint@e940be7) feat: Use ESLINT_USE_FLAT_CONFIG environment variable for flat config ([#16356](eslint/eslint#16356)) (Tomer Aberbach) - [`dd0c58f`](eslint/eslint@dd0c58f) feat: Swap out Globby for custom globbing solution. ([#16369](eslint/eslint#16369)) (Nicholas C. Zakas) #### Bug Fixes - [`df77409`](eslint/eslint@df77409) fix: use `baseConfig` constructor option in FlatESLint ([#16432](eslint/eslint#16432)) (Milos Djermanovic) - [`33668ee`](eslint/eslint@33668ee) fix: Ensure that glob patterns are matched correctly. ([#16449](eslint/eslint#16449)) (Nicholas C. Zakas) - [`740b208`](eslint/eslint@740b208) fix: ignore messages without a `ruleId` in `getRulesMetaForResults` ([#16409](eslint/eslint#16409)) (Francesco Trotta) - [`8f9759e`](eslint/eslint@8f9759e) fix: `--ignore-pattern` in flat config mode should be relative to `cwd` ([#16425](eslint/eslint#16425)) (Milos Djermanovic) - [`325ad37`](eslint/eslint@325ad37) fix: make `getRulesMetaForResults` return a plain object in trivial case ([#16438](eslint/eslint#16438)) (Francesco Trotta) - [`a2810bc`](eslint/eslint@a2810bc) fix: Ensure that directories can be unignored. ([#16436](eslint/eslint#16436)) (Nicholas C. Zakas) - [`35916ad`](eslint/eslint@35916ad) fix: Ensure unignore and reignore work correctly in flat config. ([#16422](eslint/eslint#16422)) (Nicholas C. Zakas) #### Documentation - [`651649b`](eslint/eslint@651649b) docs: Core concepts page ([#16399](eslint/eslint#16399)) (Ben Perlmutter) - [`631cf72`](eslint/eslint@631cf72) docs: note --ignore-path not supported with flat config ([#16434](eslint/eslint#16434)) (Andy Edwards) - [`1692840`](eslint/eslint@1692840) docs: fix syntax in examples for new config files ([#16427](eslint/eslint#16427)) (Milos Djermanovic) - [`d336cfc`](eslint/eslint@d336cfc) docs: Document extending plugin with new config ([#16394](eslint/eslint#16394)) (Ben Perlmutter) #### Chores - [`e917a9a`](eslint/eslint@e917a9a) ci: add node v19 ([#16443](eslint/eslint#16443)) (Koichi ITO) - [`4b70b91`](eslint/eslint@4b70b91) chore: Add VS Code issues link ([#16423](eslint/eslint#16423)) (Nicholas C. Zakas) - [`232d291`](eslint/eslint@232d291) chore: suppress a Node.js deprecation warning ([#16398](eslint/eslint#16398)) (Koichi ITO) </details> --- ### Configuration 📅 **Schedule**: Branch creation - At any time (no schedule defined), Automerge - At any time (no schedule defined). 🚦 **Automerge**: Disabled by config. Please merge this manually once you are satisfied. ♻ **Rebasing**: Whenever PR becomes conflicted, or you tick the rebase/retry checkbox. 🔕 **Ignore**: Close this PR and you won't be reminded about this update again. --- - [ ] If you want to rebase/retry this PR, click this checkbox. --- This PR has been generated by [Renovate Bot](https://github.com/renovatebot/renovate).  Co-authored-by: cabr2-bot <cabr2.help@gmail.com> Reviewed-on: https://codeberg.org/Calciumdibromid/CaBr2/pulls/1599 Reviewed-by: Epsilon_02 <epsilon_02@noreply.codeberg.org> Co-authored-by: Calciumdibromid Bot <cabr2_bot@noreply.codeberg.org> Co-committed-by: Calciumdibromid Bot <cabr2_bot@noreply.codeberg.org>

bpmutter added 4 commits October 3, 2022 20:00

docs: add stubbed out core concepts page

08f3348

partial stub out of page

9c88311

draft full page

d9213f4

copy edits

220c5df

eslint-github-bot bot added triage An ESLint team member will look at this issue soon documentation Relates to ESLint's documentation labels Oct 8, 2022

remove editor generated markdown toc

ceaac77

nzakas requested changes Oct 13, 2022

View reviewed changes

bpmutter and others added 2 commits October 17, 2022 20:38

Apply suggestions from NZ code review

42d5fe3

Co-authored-by: Nicholas C. Zakas <nicholas@humanwhocodes.com>

draft NZ feedback changes

ca2c4ac

bpmutter added 2 commits October 17, 2022 22:10

make paragraphs 1-line

ff60864

copy edits

5d846dc

bpmutter requested a review from nzakas October 18, 2022 02:15

nzakas requested changes Oct 19, 2022

View reviewed changes

bpmutter and others added 3 commits October 19, 2022 21:36

Apply suggestions from NZ code review

d618092

Co-authored-by: Nicholas C. Zakas <nicholas@humanwhocodes.com>

remove .vscode conf

e54abf1

mention espree

4832f3a

bpmutter requested a review from nzakas October 20, 2022 01:49

nzakas approved these changes Oct 21, 2022

View reviewed changes

nzakas merged commit 651649b into eslint:main Oct 21, 2022

mdjermanovic mentioned this pull request Oct 22, 2022

docs: update formatters template #16454

Merged

1 task

eslint-github-bot bot locked and limited conversation to collaborators Apr 20, 2023

eslint-github-bot bot added the archived due to age This issue has been archived; please open a new issue for any further discussion label Apr 20, 2023

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: Core concepts page #16399

docs: Core concepts page #16399

bpmutter commented Oct 8, 2022 •

edited

netlify bot commented Oct 8, 2022 •

edited

nzakas left a comment

nzakas Oct 13, 2022

nzakas commented Oct 14, 2022

bpmutter commented Oct 18, 2022

bpmutter commented Oct 18, 2022

nzakas left a comment

nzakas Oct 19, 2022

bpmutter Oct 20, 2022

nzakas Oct 19, 2022

bpmutter Oct 20, 2022

bpmutter commented Oct 20, 2022

nzakas left a comment


		## Plugins

		An ESLint plugin is an npm module that contains a set of ESLint rules.

docs: Core concepts page #16399

docs: Core concepts page #16399

Conversation

bpmutter commented Oct 8, 2022 • edited

Prerequisites checklist

What is the purpose of this pull request? (put an "X" next to an item)

What changes did you make? (Give an overview)

Is there anything you'd like reviewers to focus on?

netlify bot commented Oct 8, 2022 • edited

✅ Deploy Preview for docs-eslint ready!

nzakas left a comment

Choose a reason for hiding this comment

nzakas Oct 13, 2022

Choose a reason for hiding this comment

nzakas commented Oct 14, 2022

bpmutter commented Oct 18, 2022

bpmutter commented Oct 18, 2022

nzakas left a comment

Choose a reason for hiding this comment

nzakas Oct 19, 2022

Choose a reason for hiding this comment

bpmutter Oct 20, 2022

Choose a reason for hiding this comment

nzakas Oct 19, 2022

Choose a reason for hiding this comment

bpmutter Oct 20, 2022

Choose a reason for hiding this comment

bpmutter commented Oct 20, 2022

nzakas left a comment

Choose a reason for hiding this comment

bpmutter commented Oct 8, 2022 •

edited

netlify bot commented Oct 8, 2022 •

edited