diff --git a/docs/CONTRIBUTION.md b/docs/CONTRIBUTION.md index 885bd67..43e4390 100644 --- a/docs/CONTRIBUTION.md +++ b/docs/CONTRIBUTION.md @@ -14,7 +14,8 @@ To create a new Vale rule, make sure you have the following software installed. ### Prerequisites -- [Vale](https://vale.sh/docs/vale-cli/installation/) v3.6.0 or later +- [Vale](https://vale.sh/docs/vale-cli/installation/) v3.6.0 or later. +- [Node.js](https://nodejs.org/en/download/prebuilt-installer) v20.0.0 or later. - You have discussed the rule with the Docs & Education team and have received approval. - Cloned the repository and have the latest `main` branch version. @@ -22,20 +23,22 @@ To create a new Vale rule, make sure you have the following software installed. Use the following steps to create a new Vale rule. -1. Identify the package to which the rule should be added. Most rules are added to the `spectrocloud` package, as that is a public-facing package. +1. Issue the command, `npm ci` to install the required dependencies. -2. Create a YAML file in the `packages/spectrocloud/styles/spectrocloud` directory. Name the file according to the rule you are creating. For example, if you create a rule to check for ableism, name the file `ableism.yml`. Try to keep the rule name simple. +2. Identify the package to which the rule should be added. Most rules are added to the `spectrocloud` package, as that is a public-facing package. + +3. Create a YAML file in the `packages/spectrocloud/styles/spectrocloud` directory. Name the file according to the rule you are creating. For example, if you create a rule to check for ableism, name the file `ableism.yml`. Try to keep the rule name simple. > [!WARNING] > Make sure the file ends with `.yml` and not `yaml`. Otherwise, Vale will not recognize the file as a style file. -3. Follow the [Vale documentation](https://vale.sh/docs/topics/styles/) to create the rule. +4. Follow the [Vale documentation](https://vale.sh/docs/topics/styles/) to create the rule. -4. We recommend you test the rule using [Vale Studio](https://studio.vale.sh/) along with a sample markdown file. This is an excellent way to ensure the rule works as expected while receiving immediate feedback. +5. We recommend you test the rule using [Vale Studio](https://studio.vale.sh/) along with a sample markdown file. This is an excellent way to ensure the rule works as expected while receiving immediate feedback. -5. Once satisfied with the rule, create a new folder in the `packages/spectrocloud/test/` folder. For example, if you create a rule to check for ableism, create a folder named `ableism`. +6. Once satisfied with the rule, create a new folder in the `packages/spectrocloud/test/` folder. For example, if you create a rule to check for ableism, create a folder named `ableism`. -6. Inside the folder, create the following three files: +7. Inside the folder, create the following three files: - `pass.md`: A markdown file that passes the rule. - `fail.md`: A markdown file that fails the rule. @@ -53,15 +56,15 @@ Use the following steps to create a new Vale rule. > [!NOTE] > The `.vale.init` file explicitly specifies the rule to be tested. This is necessary because Vale does not automatically detect the rule. -7. Add sample markdown text to the `pass.md` and `fail.md` files. Make sure the `fail.md` file contains content that violates the rule you created. Remember, the test is only as good as the quality of the sample markdown. Try to include multiple scenarios to feel confident the rule behaves as expected. +8. Add sample markdown text to the `pass.md` and `fail.md` files. Make sure the `fail.md` file contains content that violates the rule you created. Remember, the test is only as good as the quality of the sample markdown. Try to include multiple scenarios to feel confident the rule behaves as expected. > [!TIP] > Try to use codeblocks and indented text. These are common areas where rules are applied and often missed during development. -8. You can test your rule by using the following options. +9. You can test your rule by using the following options. -- Issue the command `make tests`. This will start the test suite and test all the rules of all packages. + - Issue the command `make tests`. This will start the test suite and test all the rules of all packages. -- Navigate to the test folder where you have the three files and issue the command `vale --config=.vale.ini pass.md` or `vale --config=.vale.ini fail.md`. This will test the rule against the markdown files. + - Navigate to the test folder where you have the three files and issue the command `vale --config=.vale.ini pass.md` or `vale --config=.vale.ini fail.md`. This will test the rule against the markdown files. -9. Once satisfied with the rule, create a Pull Request (PR) and submit it for review. Once the PR is ready for review, the automatic test suite will start and verify all required files are present and that the rule works as expected. +10. Once satisfied with the rule, create a Pull Request (PR) and submit it for review. Once the PR is ready for review, the automatic test suite will start and verify all required files are present and that the rule works as expected.