From 0ee600a4176509d9c5577bd1a01702bcdc3841e6 Mon Sep 17 00:00:00 2001 From: Patrick McElhaney Date: Mon, 15 Aug 2022 09:56:56 -0400 Subject: [PATCH 1/4] docs: package.json conventions --- docs/src/developer-guide/code-conventions.md | 4 +- .../package-json-conventions.md | 91 +++++++++++++++++++ 2 files changed, 94 insertions(+), 1 deletion(-) create mode 100644 docs/src/developer-guide/package-json-conventions.md diff --git a/docs/src/developer-guide/code-conventions.md b/docs/src/developer-guide/code-conventions.md index 9b639c36cb9..fa42a99c254 100644 --- a/docs/src/developer-guide/code-conventions.md +++ b/docs/src/developer-guide/code-conventions.md @@ -2,7 +2,6 @@ title: Code Conventions layout: doc edit_link: https://github.com/eslint/eslint/edit/main/docs/src/developer-guide/code-conventions.md - --- Code conventions for ESLint are determined by @@ -12,3 +11,6 @@ The rationales for the specific rules in use can be found by looking to the project documentation for any given rule. If the rule is one of our own, see our own [rule documentation](https://eslint.org/docs/rules/) and otherwise, see the documentation of the plugin in which the rule can be found. + +If you need to make changes to a `package.json` file, please see the +[package.json conventions](./package-json-conventions.md). diff --git a/docs/src/developer-guide/package-json-conventions.md b/docs/src/developer-guide/package-json-conventions.md new file mode 100644 index 00000000000..b7093744889 --- /dev/null +++ b/docs/src/developer-guide/package-json-conventions.md @@ -0,0 +1,91 @@ +--- +title: Package.json Conventions +layout: doc +edit_link: https://github.com/eslint/eslint/edit/main/docs/src/developer-guide/package-json-conventions.md +--- + +# Package.json Script Naming Conventions + +The following applies to the "scripts" section of `package.json` files. + +## Names + +npm script names MUST contain only lower case letters, `:` to separates parts, `-` to separate words, and `+` to separate file extensions. Each part name SHOULD be either a full English word (e.g. `coverage` not `cov`) or a well-known initialism in all lowercase (e.g. `wasm`). + +Here is a summary of the proposal in EBNF. + +```ebnf +name = life-cycle | main ":fix"? target? option* ":watch"? + +life-cycle = prepare | preinstall | install | postinstall | prepublish | preprepare | prepare | postprepare | prepack | postpack | prepublishOnly; + +main = "build" | "lint" | "start" | "test"; + +target = ":" word ("-" word)* | extension ("+" extension)*; + +option = ":" word ("-" word)*; + +word = [a-z]+; + +extension = [a-z0-9]+; +``` + +## Order + +The script names MUST appear in the package.json file in alphabetical order. The other conventions outlined in this document ensure that alphabetical order will coincide with logical groupings. + +## Main Script Names + +With the exception of [npm life cycle scripts](https://docs.npmjs.com/cli/v8/using-npm/scripts#life-cycle-scripts) all script names MUST begin with one of the following names. + +### Build + +Scripts that generate a set of files from source code and / or data MUST have names that begin with `build`. + +If a package contains any `build:*` scripts, there MAY be a script named `build`. If so, SHOULD produce the same output as running each of the `build` scripts individually. It MUST produce a subset of the output from running those scripts. + +### Lint + +Scripts that statically analyze files (mostly, but not limited to running `eslint` itself) MUST have names that begin with `lint`. + +If a package contains any `lint:*` scripts, there SHOULD be a script named `lint` and it MUST run all of the checks that would have been run if each `lint:*` script was called individually. + +If fixing is available, a linter MUST NOT apply fixes UNLESS the script contains the `:fix` modifier (see below). + +### Start + +A `start` script is used to start a server. As of this writing, no ESLint package has more than one `start` script, so there's no need `start` to have any modifiers. + +### Test + +Scripts that execute code in order to ensure the actual behavior matches expected behavior MUST have names that begin with `test`. + +If a package contains any `test:*` scripts, there SHOULD be a script named `test` and it MUST run of all of the tests that would have been run if each `test:*` script was called individually. + +A test script SHOULD NOT include linting. + +A test script SHOULD report test coverage when possible. + +## Modifiers + +One or more of the following modifiers MAY be appended to the standard script names above. If a target has modifiers, they MUST be in the order in which they appear below (e.g. `lint:fix:js:watch` not `lint:watch:js:fix`) + +### Fix + +If it's possible for a linter to fix problems that it finds, add a copy of the script with `:fix` appended to the end that also fixes. + +### Target + +The name of the target of the action being run. In the case of a `build` script, it SHOULD identify the build artifact(s), e.g. "javascript" or "css" or "website". In the case of a `lint` or `test` script, it SHOULD identify the item(s) being linted or tested. In the case of a `start` script, it SHOULD identify which server is starting. + +A target MAY refer to a list of affected file extensions (such as `cjs` or `less`) delimited by a `+`. If there is more than one extension, the list SHOULD be alphabetized. When a file extension has variants (such as `cjs` for CommonJS and `mjs` for ESM), the common part of the extension MAY be used instead of explicitly listing out all of the variants (e.g. `js` instead of `cjs+jsx+mjs`). + +The target SHOULD NOT refer to name of the name of the tool that's performing the action (`eleventy`, `webpack`, etc.) + +### Options + +Additional options that don't fit under the other modifiers. + +### Watch + +If a script watches the filesystem and responds to changes, add `:watch` to the script name. From 1f2b3b5b40d98a783fbd0984c88f8f8588323a1e Mon Sep 17 00:00:00 2001 From: Patrick McElhaney Date: Mon, 15 Aug 2022 10:14:01 -0400 Subject: [PATCH 2/4] remove top level heading --- docs/src/developer-guide/package-json-conventions.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/docs/src/developer-guide/package-json-conventions.md b/docs/src/developer-guide/package-json-conventions.md index b7093744889..9f8960c31d1 100644 --- a/docs/src/developer-guide/package-json-conventions.md +++ b/docs/src/developer-guide/package-json-conventions.md @@ -4,8 +4,6 @@ layout: doc edit_link: https://github.com/eslint/eslint/edit/main/docs/src/developer-guide/package-json-conventions.md --- -# Package.json Script Naming Conventions - The following applies to the "scripts" section of `package.json` files. ## Names From b6b479d5b2726825971d208b6255c3ea6b793c08 Mon Sep 17 00:00:00 2001 From: Patrick McElhaney Date: Wed, 17 Aug 2022 07:26:39 -0400 Subject: [PATCH 3/4] typo Co-authored-by: Strek --- docs/src/developer-guide/package-json-conventions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/src/developer-guide/package-json-conventions.md b/docs/src/developer-guide/package-json-conventions.md index 9f8960c31d1..4733b425264 100644 --- a/docs/src/developer-guide/package-json-conventions.md +++ b/docs/src/developer-guide/package-json-conventions.md @@ -8,7 +8,7 @@ The following applies to the "scripts" section of `package.json` files. ## Names -npm script names MUST contain only lower case letters, `:` to separates parts, `-` to separate words, and `+` to separate file extensions. Each part name SHOULD be either a full English word (e.g. `coverage` not `cov`) or a well-known initialism in all lowercase (e.g. `wasm`). +npm script names MUST contain only lower case letters, `:` to separate parts, `-` to separate words, and `+` to separate file extensions. Each part name SHOULD be either a full English word (e.g. `coverage` not `cov`) or a well-known initialism in all lowercase (e.g. `wasm`). Here is a summary of the proposal in EBNF. From c77e3605050ad875885894ba3e9b0e4c3bbac1a1 Mon Sep 17 00:00:00 2001 From: "Nicholas C. Zakas" Date: Wed, 24 Aug 2022 15:16:43 -0700 Subject: [PATCH 4/4] Update docs/src/developer-guide/code-conventions.md Co-authored-by: Nitin Kumar --- docs/src/developer-guide/code-conventions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/src/developer-guide/code-conventions.md b/docs/src/developer-guide/code-conventions.md index 2ad9a9df3d0..18b72740322 100644 --- a/docs/src/developer-guide/code-conventions.md +++ b/docs/src/developer-guide/code-conventions.md @@ -12,4 +12,4 @@ our own [rule documentation](https://eslint.org/docs/rules/) and otherwise, see the documentation of the plugin in which the rule can be found. If you need to make changes to a `package.json` file, please see the -[package.json conventions](./package-json-conventions.md). +[package.json conventions](./package-json-conventions).