CONTRIBUTING.md

Contributing

👍🎉 First off, thanks for taking the time to contribute! 🎉👍

Reporting bugs

To report a bug, open an issue.

If you are unsure whether something is a bug or not, please open an issue. Insufficient documentation is also a bug.

Suggesting new features

New features can be a new rule, anew option for an existing rule, or new functionality for existing rules.

To suggest a new feature, open an issue.

Making pull requests

(If this is your first pull request on GitHub, checkout this guide.)

Getting started

• This is a TypeScript project. You need to have a recentish version of Node.js and npm installed.
• Install all project and development dependencies by running npm ci.
• Test that everything is installed correctly by running npm test.

We use ESLint and Prettier to lint and format our code base. They will be automatically installed as dependencies but you might need additional editor plugins for a good IDE experience. We recommend using VSCode together with the ESLint plugin for a great editing experience.

Creating a new rule

The following steps will walk you through the process of creating a new rule.

1. Run npm run new <rule-name>:

   This will automatically create 3 files:

   1. lib/rules/rule-name.ts - Implementation + meta information (name, category, short desc, etc.)
   2. tests/lib/rules/rule-name.ts - Functional tests
   3. docs/rules/rule-name.md - Documentation

   These 3 files contain all the information about your new rule. You only need to touch these 3 files to add your rule.

2. Add meta information:

   Fill in the rule's meta information in the meta object. This includes a short description, its category, type, and more.

   Note: Do not set recommended: true. This will add your rule to the node-dependencies/recommended configuration. We view additions to the node-dependencies/recommended configuration as breaking changes. If you want your rule to be included in the node-dependencies/recommended configuration in the next major release, leave the generated TODO comment as is.

   Once you added a short description and the category, run npm run update. This will update a few generated files to include your rule in the website and more.

3. Implement your rule:

   The createRule function will be where you implement your rule.

   The valid-engines and valid-semver rules are good examples to see how we usually implement rules.

4. Test your rule:

   Add test for every feature and option of your rule. (We use ESLint's RuleTester for testing rules.)

   Use npm test to run all tests.

5. Document your rule:

   The documentation should contain a description of the rule and the problem it detects/solves, examples, all features, all options, and any additional information relevant to the rule.

   You can view the documentation live in your browser by running npm run build && npm run docs:watch. The live view will automatically update when you make changes to the documentation. However, you have to re-run the command to see changes to the rule implementation.

Updating documentation

Almost all Markdown files of our website and the project README.md are partially or completely generated.

The following files are completely generated and must not be modified directly:

• docs/index.md - change this section of the project README.md instead.
• docs/rules/index.md
• docs/user-guide/index.md - change this section of the project README.md instead.

The following files are partially generated:

• README.md: The rules table is generated.
• docs/rules/*.md: Everything above the ":book: Rule Details" heading and below the ":mag: Implementation" heading is generated.

Only change the non-generated parts in these files.

After you changed the documentation, run npm run update to update all generated files. Be sure to always run this command before you commit any documentation changes.

You can view changes to the website locally by running npm run docs:watch.

Testing

Aside from npm test, there are also a few other ways to manually test new features, changes, and new rules.

1. Test your rule and the whole plugin by installing it.

   If there is a project/code base you want to test your rule/the entire plugin on, then installing this project will be the right solution.

   Setup ESLint in the target project. Instead of installing the eslint-plugin-node-dependencies from the npm registry, install your local eslint-plugin-node-dependencies project using the relative path to the project.

   Example:

   projects/
   ├── target/
   |   └── package.json
   └── eslint-plugin-node-dependencies/
       └── package.json
   

   projects/target$ npm i -D ../eslint-plugin-node-dependencies

   Note: If you make changes to the implementation of a rule, you'll have to run npm run build before these changes show up in the target project.