and used npm-run-all2 to define verification script groups that can be parallelized while also enabling scripts to be run independantly
for semantic-release/.github#19
because of a known issue with v20.6.0 that we might as well avoid since we are restricting the
supported ranges at this point anyway: https://github.com/nodejs/node/issues/49497
BREAKING CHANGE: the minimum supported version for the v20 range of node has been raised slightly to
v20.6.1 to avoid a known node bug
# 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
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.
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.
Before pushing your code changes make sure there are no linting errors with `npm run lint`.
> [!IMPORTANT]
> Before pushing your code changes, be sure to run the verification for the project with `npm test`.
**Tips**:
[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.
- 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.
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
### Tests
```shell
$ npm run <script-name>
```
Running the integration test requires you to install [Docker](https://docs.docker.com/engine/installation) on your machine.
#### Lint
##### Prettier
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
All the [semantic-release](https://github.com/semantic-release) repositories use [Commitizen](https://github.com/commitizen/cz-cli) to help you create [valid commit messages](#commit-message-guidelines).
After staging your changes with `git add`, run `npm run cm` to start the interactive commit message CLI.
Assuming you have [installed Commitizen](https://github.com/commitizen/cz-cli#installing-the-command-line-tool), run `git cz` to start the interactive commit message CLI rather than `git commit` when committing.
@ -69,7 +69,7 @@ The table below shows which commit message gets you which release type when `sem
### Automation with CI
**semantic-release** is meant to be executed on the CI environment after every successful build on the release branch.
This way no human is directly involved in the release process and the releases are guaranteed to be [unromantic and unsentimental](http://sentimentalversioning.org).
This way no human is directly involved in the release process and the releases are guaranteed to be [unromantic and unsentimental](https://github.com/dominictarr/sentimental-versioning#readme).
### Triggering a release
@ -110,9 +110,9 @@ In order to use **semantic-release** you need:
@ -127,7 +127,7 @@ It allows to configure **semantic-release** to write errors to a specific stream
Type: `Object``Boolean`<br>
And object with [`lastRelease`](#lastrelease), [`nextRelease`](#nextrelease), [`commits`](#commits) and [`releases`](#releases) if a release is published or `false` if no release was published.
An object with [`lastRelease`](#lastrelease), [`nextRelease`](#nextrelease), [`commits`](#commits) and [`releases`](#releases) if a release is published or `false` if no release was published.
#### lastRelease
@ -159,7 +159,7 @@ Example:
Type: `Array<Object>`
The list of commit included in the new release.<br>
The list of commit(s) included in the new release.<br>
@ -195,7 +195,7 @@ If you need more control over the timing of releases, see [Triggering a release]
## Can I set the initial release version of my package to `0.0.1`?
This is not supported by **semantic-release** as it's not considered a good practice, mostly because [Semantic Versioning](https://semver.org) rules applies differently to major version zero.
This is not supported by semantic-release. [Semantic Versioning](https://semver.org/) rules apply differently to major version zero and supporting those differences is out of scope and not one of the goals of the semantic-release project.
If your project is under heavy development, with frequent breaking changes, and is not production ready yet we recommend [publishing pre-releases](../recipes/release-workflow/pre-releases.md#publishing-pre-releases).
**semantic-release** is written using the latest [ECMAScript 2017](https://www.ecma-international.org/publications/standards/Ecma-262.htm) features, without transpilation which **requires Node version 18.0.0 or higher**.
**semantic-release** is written using the latest [ECMAScript 2017](https://www.ecma-international.org/publications/standards/Ecma-262.htm) features, without transpilation which **requires Node version 20.8.1 or higher**.
**semantic-release** is meant to be used in a CI environment as a development support tool, not as a production dependency.
Therefore, the only constraint is to run the `semantic-release` in a CI environment providing version of Node that meets our version requirement.
@ -6,16 +6,3 @@ In order to use **semantic-release** you must follow these steps:
2. Configure your Continuous Integration service to [run **semantic-release**](./ci-configuration.md#run-semantic-release-only-after-all-tests-succeeded)
3. Configure your Git repository and package manager repository [authentication](ci-configuration.md#authentication) in your Continuous Integration service
4. Configure **semantic-release** [options and plugins](./configuration.md#configuration)
Alternatively those steps can be easily done with the [**semantic-release** interactive CLI](https://github.com/semantic-release/cli):
```bash
cd your-module
npx semantic-release-cli setup
```
See the [semantic-release-cli](https://github.com/semantic-release/cli#what-it-does) documentation for more details.
**Note**: only a limited number of options, CI services and plugins are currently supported by `semantic-release-cli`.
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
