simon/semantic-release
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

docs(contributing): updated details about local verification

Browse Source
This commit is contained in:
Matt Travi 2023-10-08 09:39:17 -05:00
parent 842c0eb8bc
commit 579259c578
No known key found for this signature in database
GPG Key ID: 8C173646C24FED70
1 changed files with 54 additions and 18 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

72
CONTRIBUTING.md
View File

@ -241,44 +241,80 @@ $ git clone https://github.com/semantic-release/<repo-name>
$ cd <repo-name>
# Assign the original repo to a remote called "upstream"
$ git remote add upstream https://github.com/semantic-release/<repo-name>
# Switch your node version to the version defined by the project as the development version
# This step assumes you have already installed and configured https://github.com/nvm-sh/nvm
# You may need to run `nvm install` if you have not already installed the development node version
$ nvm use
# Install the dependencies
$ npm install
```
### Lint
### Verification
[//]: # "TODO: rework these docs"
The `test` script is structured to execute as much of the verification for the project as possible.
Ensuring that the `test` script fully passes in the node version defined as the development version in the `.nvmrc`
minimizes the chances of the test workflow failing after pushing your changes.
All the [semantic-release](https://github.com/semantic-release) repositories use [XO](https://github.com/sindresorhus/xo) for linting and [Prettier](https://prettier.io) for formatting.
Prettier formatting will be automatically verified and fixed by XO.
> [!IMPORTANT]
> Before pushing your code changes, be sure to run the verification for the project with `npm test`.
Before pushing your code changes make sure there are no linting errors with `npm run lint`.
[npm-run-all2](https://www.npmjs.com/package/npm-run-all2) is used to enable running multiple independent lint and test
scripts together from the `test` script.
This enables the test script to not only run all scripts, but also parallelize some of the scripts to optimize the overall
time required for verification.
**Tips**:
When a failure occurs with the `test`, the output can be a bit confusing because there may be output from multiple parallel
scripts mixed together.
To investigate the failure with cleaner output, re-run the problematic script directly using the script name from the label
included on the left side of the output
- Most linting errors can be automatically fixed with `npm run lint -- --fix`.
- Install the [XO plugin](https://github.com/sindresorhus/xo#editor-plugins) for your editor to see linting errors directly in your editor and automatically fix them on save.
```shell
$ npm run <script-name>
```
### Tests
#### Lint
[//]: # "TODO: rework these docs too"
##### Prettier
Running the integration test requires you to install [Docker](https://docs.docker.com/engine/installation) on your machine.
All the [semantic-release](https://github.com/semantic-release) repositories use [Prettier](https://prettier.io) for formatting.
Prettier formatting will be automatically verified by the `lint:prettier` script, included in the `test` script.
> [!NOTE]
> Most linting errors can be automatically fixed with `npm run lint:prettier:fix`.
##### Other Lint Tools
Other tools are used for specific compatibility concerns, but are less likely to result in failures in common contributions.
Please follow the guidance of these tools if failures are encountered.
#### Tests
> [!NOTE]
> Before pushing your code changes make sure all **tests pass** and the unit test **coverage is 100%**:
All the [semantic-release](https://github.com/semantic-release) repositories use [AVA](https://github.com/avajs/ava) for writing and running tests.
Before pushing your code changes make sure all **tests pass** and the **coverage is 100%**:
```bash
$ npm run test
```
**Tips:** During development you can:
During development, you can:
- run only a subset of test files with `ava <glob>`, for example `ava test/mytestfile.test.js`
- run in watch mode with `ava -w` to automatically run a test file when you modify it
- run only the test you are working on by adding [`.only` to the test definition](https://github.com/avajs/ava#running-specific-tests)
##### Unit Tests
```bash
$ npm run test:unit
```
##### Integration Tests
> [!IMPORTANT]
> Running the integration test requires you to install [Docker](https://docs.docker.com/engine/installation) on your machine.
```bash
$ npm run test:integration
```
### Commits
[//]: # "TODO: these docs are already out of date. i'd value cleaning up the commitizen support, but w/o a special script"