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.

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

docs: Core concepts page #16399

Merged
merged 12 commits into from Oct 21, 2022
Merged

docs: Core concepts page #16399

merged 12 commits into from Oct 21, 2022

Conversation

bpmutter
Copy link
Contributor

@bpmutter bpmutter commented Oct 8, 2022

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:

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

@eslint-github-bot 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
@netlify
Copy link

netlify bot commented Oct 8, 2022

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...

QR Code

Use your smartphone camera to open QR code link.

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

Copy link
Member

@nzakas nzakas left a comment

Choose a reason for hiding this comment

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

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:

  1. Shareable configs - this is the largest part of the ESLint ecosystem, so I think it makes sense to mention this after configuration files.
  2. 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.
  3. 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 Outdated Show resolved Hide resolved
docs/src/user-guide/core-concepts.md Outdated Show resolved Hide resolved
docs/src/user-guide/core-concepts.md Outdated Show resolved Hide resolved
docs/src/user-guide/core-concepts.md Outdated Show resolved Hide resolved

## Plugins

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

Choose a reason for hiding this comment

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

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

docs/src/user-guide/core-concepts.md Outdated Show resolved Hide resolved
docs/src/user-guide/core-concepts.md Outdated Show resolved Hide resolved
docs/src/user-guide/core-concepts.md Outdated Show resolved Hide resolved
docs/src/user-guide/core-concepts.md Outdated Show resolved Hide resolved
docs/src/user-guide/core-concepts.md Outdated Show resolved Hide resolved
@nzakas
Copy link
Member

nzakas commented Oct 14, 2022

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.

bpmutter and others added 2 commits October 17, 2022 20:38
Co-authored-by: Nicholas C. Zakas <nicholas@humanwhocodes.com>
@bpmutter
Copy link
Contributor Author

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 bpmutter requested a review from nzakas October 18, 2022 02:15
@bpmutter
Copy link
Contributor Author

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

Copy link
Member

@nzakas nzakas left a comment

Choose a reason for hiding this comment

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

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

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

Choose a reason for hiding this comment

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

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

Copy link
Contributor Author

Choose a reason for hiding this comment

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

yep, will remove!


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.
Copy link
Member

Choose a reason for hiding this comment

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

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

Copy link
Contributor Author

Choose a reason for hiding this comment

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

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

docs/src/user-guide/core-concepts.md Outdated Show resolved Hide resolved
bpmutter and others added 3 commits October 19, 2022 21:36
Co-authored-by: Nicholas C. Zakas <nicholas@humanwhocodes.com>
@bpmutter bpmutter requested a review from nzakas October 20, 2022 01:49
@bpmutter
Copy link
Contributor Author

@nzakas implemented your feedback. ready for re-review

nzakas
nzakas approved these changes Oct 21, 2022
Copy link
Member

@nzakas nzakas left a comment

Choose a reason for hiding this comment

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

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

@nzakas nzakas merged commit 651649b into eslint:main Oct 21, 2022
20 checks passed
crapStone pushed a commit to Calciumdibromid/CaBr2 that referenced this pull request Oct 24, 2022
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 ([#&#8203;16420](eslint/eslint#16420)) (Yuki Hirasawa)
-   [`28d1902`](eslint/eslint@28d1902) feat: `no-implicit-globals` supports `exported` block comment ([#&#8203;16343](eslint/eslint#16343)) (Sosuke Suzuki)
-   [`e940be7`](eslint/eslint@e940be7) feat: Use ESLINT_USE_FLAT_CONFIG environment variable for flat config ([#&#8203;16356](eslint/eslint#16356)) (Tomer Aberbach)
-   [`dd0c58f`](eslint/eslint@dd0c58f) feat: Swap out Globby for custom globbing solution. ([#&#8203;16369](eslint/eslint#16369)) (Nicholas C. Zakas)

#### Bug Fixes

-   [`df77409`](eslint/eslint@df77409) fix: use `baseConfig` constructor option in FlatESLint ([#&#8203;16432](eslint/eslint#16432)) (Milos Djermanovic)
-   [`33668ee`](eslint/eslint@33668ee) fix: Ensure that glob patterns are matched correctly. ([#&#8203;16449](eslint/eslint#16449)) (Nicholas C. Zakas)
-   [`740b208`](eslint/eslint@740b208) fix: ignore messages without a `ruleId` in `getRulesMetaForResults` ([#&#8203;16409](eslint/eslint#16409)) (Francesco Trotta)
-   [`8f9759e`](eslint/eslint@8f9759e) fix: `--ignore-pattern` in flat config mode should be relative to `cwd` ([#&#8203;16425](eslint/eslint#16425)) (Milos Djermanovic)
-   [`325ad37`](eslint/eslint@325ad37) fix: make `getRulesMetaForResults` return a plain object in trivial case ([#&#8203;16438](eslint/eslint#16438)) (Francesco Trotta)
-   [`a2810bc`](eslint/eslint@a2810bc) fix: Ensure that directories can be unignored. ([#&#8203;16436](eslint/eslint#16436)) (Nicholas C. Zakas)
-   [`35916ad`](eslint/eslint@35916ad) fix: Ensure unignore and reignore work correctly in flat config. ([#&#8203;16422](eslint/eslint#16422)) (Nicholas C. Zakas)

#### Documentation

-   [`651649b`](eslint/eslint@651649b) docs: Core concepts page ([#&#8203;16399](eslint/eslint#16399)) (Ben Perlmutter)
-   [`631cf72`](eslint/eslint@631cf72) docs: note --ignore-path not supported with flat config ([#&#8203;16434](eslint/eslint#16434)) (Andy Edwards)
-   [`1692840`](eslint/eslint@1692840) docs: fix syntax in examples for new config files ([#&#8203;16427](eslint/eslint#16427)) (Milos Djermanovic)
-   [`d336cfc`](eslint/eslint@d336cfc) docs: Document extending plugin with new config ([#&#8203;16394](eslint/eslint#16394)) (Ben Perlmutter)

#### Chores

-   [`e917a9a`](eslint/eslint@e917a9a) ci: add node v19 ([#&#8203;16443](eslint/eslint#16443)) (Koichi ITO)
-   [`4b70b91`](eslint/eslint@4b70b91) chore: Add VS Code issues link ([#&#8203;16423](eslint/eslint#16423)) (Nicholas C. Zakas)
-   [`232d291`](eslint/eslint@232d291) chore: suppress a Node.js deprecation warning ([#&#8203;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.

---

 - [ ] <!-- rebase-check -->If you want to rebase/retry this PR, click this checkbox.

---

This PR has been generated by [Renovate Bot](https://github.com/renovatebot/renovate).
<!--renovate-debug:eyJjcmVhdGVkSW5WZXIiOiIzMi4yNDEuNSIsInVwZGF0ZWRJblZlciI6IjMyLjI0MS4xMCJ9-->

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>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
documentation Relates to ESLint's documentation triage An ESLint team member will look at this issue soon
Projects
None yet
Development

Successfully merging this pull request may close these issues.

Core Concepts documentation
2 participants