{name}
+ + + +{description}
} + { + stepEntries.length > 0 && ( +-
+ {stepEntries.map(([stepName, descriptionription]) => (
+
- {stepName} + +
+
+
+
+
+ ))}
+ 
{description}
} + { + stepEntries.length > 0 && ( +package.json version with npm version.',
+ publish:
+ 'Publish the Atom package.',
+ }}
+/>
+
+apiSpecFiles.",
+ }}
+/>
+
+.xpi file, and submits it to the Mozilla Add On store for signing. Once the package is signed, downloads the signed .xpi to a local directory.",
+ }}
+/>
+
+pom.xml (or all pom.xml files in maven projects with multiple pom.xml files) and optionally creates a commit with this version number and pushes it to master.",
+ publish:
+ "Runs mvn deploy to deploy to maven central and optionally will update to next snapshot version and merge changes to development branch.",
+ }}
+/>
+
+pom.xml and optionally in all child modules.",
+ publish:
+ "Runs one of the mvn targets deploy, package jib:build or deploy jib:build.",
+ success: "Optionally sets new snapshot version and commits it.",
+ }}
+/>
+
+gradle.properties.",
+ publish: "Triggers Gradle to publish artifacts.",
+ }}
+/>
+
+orbName option, and the circleci CLI.",
+ publish: "Publish the CircleCI orb.",
+ }}
+/>
+
+lib/**/version.rb file, verify the presence of the GEM_HOST_API_KEY environment variable, and create a credentials file with the API key.",
+ prepare:
+ 'Update the version in the lib/**/version.rb version file and build the gem.',
+ publish:
+ 'Push the Ruby gem to the gem server.',
+ }}
+/>
+
+setup.cfg and create the distribution packages.",
+ publish: "Publish the python package to a repository (default: pypi).",
+ }}
+/>
+
+pyproject.toml.",
+ }}
+/>
+
+.npmrc (if they exist), then pass the configuration to the associated plugins.",
+ }}
+/>
+
+TELEGRAM_BOT_TOKEN.",
+ success:
+ "Publish a message about the successful release to a telegram chat.",
+ fail: "Publish a message about failure to a telegram chat.",
+ }}
+/>
+
+crates.io.",
+ prepare:
+ "Write the new version number into Cargo.toml file and perform cargo check if configured.",
+ publish: "Publish the Rust crate to crates.io.",
+ }}
+/>
+
+package.json version and create the package tarball.",
+ addChannel: "Add a tag for the release.",
+ publish: "Publish to the npm registry.",
+ }}
+/>
+
+pubspec.yaml version.",
+ publish: "Publish the package onto the pub.dev registry.",
+ }}
+/>
+
+[project] section.",
+ prepare:
+ "Updates the [project].version field in pyproject.toml to match the release version.",
+ }}
+/>
+
+pyproject.toml structure.",
+ prepare:
+ "Update the version in pyproject.toml, locking and build the distribution with uv.",
+ publish:
+ "Publish the package to PyPI or a custom index using uv publish.",
+ }}
+/>
+
+
npm token created via npm token create.
Note: Only the auth-only level of npm two-factor authentication is supported.
GitHub authentication token.
Note: Only the personal token authentication is supported.
npm token for publishing to npm. Trusted publishing is the recommended approach when publishing to the official registry. A token is required when publishing to alternative registries. See CI configuration recipes for setup options.
| +| `GH_TOKEN` or `GITHUB_TOKEN` |GitHub authentication token for publishing releases. See CI configuration recipes for setup options.
| See each plugin's documentation for the environment variables required. The authentication token/credentials have to be made available in the CI service via environment variables. -See [CI configuration recipes](../recipes/ci-configurations/) for more details on how to configure environment variables in your CI service. +See [CI configuration recipes](/recipes/ci-configurations/) for examples of how to configure environment variables in your CI service. **Note**: The environment variables `GH_TOKEN`, `GITHUB_TOKEN`, `GL_TOKEN` and `GITLAB_TOKEN` can be used for both the Git authentication and the API authentication required by [@semantic-release/github](https://github.com/semantic-release/github) and [@semantic-release/gitlab](https://github.com/semantic-release/gitlab). diff --git a/src/content/docs/usage/configuration.md b/src/content/docs/usage/configuration.md index 05dac1d..f846ebc 100644 --- a/src/content/docs/usage/configuration.md +++ b/src/content/docs/usage/configuration.md @@ -2,175 +2,197 @@ title: "Configuration" --- +Configure semantic-release options, plugins, and release branches via config files, CLI arguments, or shareable configurations. + **semantic-release** configuration consists of: -- Git repository ([URL](configuration.md#repositoryurl) and options [release branches](configuration.md#branches) and [tag format](configuration.md#tagformat)) -- Plugins [declaration](configuration.md#plugins) and options -- Run mode ([debug](configuration.md#debug), [dry run](configuration.md#dryrun) and [local (no CI)](configuration.md#ci)) +- Git repository ([URL](#repositoryurl) and options [release branches](#branches) and [tag format](#tagformat)) +- Plugins [declaration](#plugins) and options +- Run mode ([debug](#debug), [dry run](#dryrun) and [local (no CI)](#ci)) -All of these options can be configured through config file, CLI arguments or by extending a [shareable configuration](shareable-configurations.md). +All of these options can be configured through config file, CLI arguments or by extending a [shareable configuration](/foundation/shareable-configurations). -Additionally, metadata of Git tags generated by **semantic-release** can be customized via standard [Git environment variables](configuration.md#git-environment-variables). +Additionally, metadata of Git tags generated by **semantic-release** can be customized via standard [Git environment variables](#git-environment-variables). ## Configuration file -**semantic-release**’s [options](configuration.md#options), mode and [plugins](plugins.md) can be set via either: +**semantic-release**’s [options](#options), mode and [plugins](/foundation/plugins) can be set via either: -- A `.releaserc` file, written in YAML or JSON, with optional extensions: `.yaml`/`.yml`/`.json`/`.js`/`.cjs`/`.mjs` -- A `release.config.(js|cjs|.mjs)` file that exports an object +- A `.releaserc` file, written in YAML or JSON, with optional extensions: `.yaml`/`.yml`/`.json`/`.js`/`.ts`/`.cjs`/`.mjs` +- A `release.config.(js|ts|cjs|mjs)` file that exports an object - A `release` key in the project's `package.json` file -Alternatively, some options can be set via CLI arguments. - -The following three examples are the same. Use main instead of master if your default branch is main. +The following three examples are the same. Use `master` instead of `main` if your default branch is `master`. - Via `release` key in the project's `package.json` file: -```json -{ - "release": { - "branches": ["master", "next"] + ```json + { + "release": { + "branches": ["main", "next"] + } } -} -``` + ``` - Via `.releaserc` file: -```json -{ - "branches": ["master", "next"] -} -``` + ```json + { + "branches": ["main", "next"] + } + ``` - Via `release.config.cjs` file: -```js -/** - * @type {import('semantic-release').GlobalConfig} - */ -module.exports = { - branches: ["master", "next"], -}; -``` + ```js + /** + * @type {import('semantic-release').GlobalConfig} + */ + module.exports = { + branches: ["main", "next"], + }; + ``` - Via `release.config.mjs` file: + ```js + /** + * @type {import('semantic-release').GlobalConfig} + */ + export default { + branches: ["main", "next"], + }; + ``` -```js -/** - * @type {import('semantic-release').GlobalConfig} - */ -export default { - branches: ["master", "next"], -}; -``` +:::note +When configuring via `package.json`, the configuration must be under the `release` property. However, when using a `.releaserc` or a `release.config.**` file, the configuration must be set without a `release` property. +::: + +## CLI arguments -- Via CLI argument: +Some [options](#options) can also be passed as command-line arguments to the `semantic-release` command. ```bash $ semantic-release --branches next ``` -**Note**: CLI arguments take precedence over options configured in the configuration file. - -**Note**: Plugin options cannot be defined via CLI arguments and must be defined in the configuration file. +:::note -**Note**: When configuring via `package.json`, the configuration must be under the `release` property. However, when using a `.releaserc` or a `release.config` file, the configuration must be set without a `release` property. +- CLI arguments take precedence over options configured in the configuration file. +- Plugin options cannot be configured through CLI arguments. See [`plugins`](#plugins) for details. + ::: ## Options -### extends +The following are **semantic-release** options you can set in the [configuration file](#configuration-file), pass as [CLI arguments](#cli-arguments), or define in a [shareable configuration](/foundation/shareable-configurations). -Type: `Array`, `String`\ -CLI arguments: `-e`, `--extends` +### `extends` -List of modules or file paths containing a [shareable configuration](shareable-configurations.md). If multiple shareable configurations are set, they will be imported in the order defined with each configuration option taking precedence over the options defined in a previous shareable configuration. +**type**: `Array`, `String`\ +**CLI arguments**: `-e`, `--extends` -**Note**: Options defined via CLI arguments or in the configuration file will take precedence over the ones defined in any shareable configuration. +List of modules or file paths containing a [shareable configuration](/foundation/shareable-configurations). If multiple shareable configurations are set, they will be imported in the order defined with each configuration option taking precedence over the options defined in a previous shareable configuration. -### branches +:::note +Options defined via CLI arguments or in the configuration file will take precedence over the ones defined in any shareable configuration. +::: -Type: `Array`, `String`, `Object`\ -Default: `['+([0-9])?(.{+([0-9]),x}).x', 'master', 'main', 'next', 'next-major', {name: 'beta', prerelease: true}, {name: 'alpha', prerelease: true}]`\ -CLI arguments: `--branches` +### `branches` + +**type**: `Array`, `String`, `Object`\ +**default**: `['+([0-9])?(.{+([0-9]),x}).x', 'master', 'main', 'next', 'next-major', {name: 'beta', prerelease: true}, {name: 'alpha', prerelease: true}]`\ +**CLI arguments**: `--branches` The branches on which releases should happen. By default **semantic-release** will release: -- regular releases to the default distribution channel from the branch `master` or `main` +- regular releases to the default distribution channel from the branch `main` or `master` - regular releases to a distribution channel matching the branch name from any existing branch with a name matching a maintenance release range (`N.N.x` or `N.x.x` or `N.x` with `N` being a number) - regular releases to the `next` distribution channel from the branch `next` if it exists - regular releases to the `next-major` distribution channel from the branch `next-major` if it exists - pre-releases to the `beta` distribution channel from the branch `beta` if it exists - pre-releases to the `alpha` distribution channel from the branch `alpha` if it exists -**Note**: Branches configuration key accepts [**micromatch**](https://github.com/micromatch/micromatch?tab=readme-ov-file#matching-features) globs. - -**Note**: If your repository does not have a release branch, then **semantic-release** will fail with an `ERELEASEBRANCHES` error message. If you are using the default configuration, you can fix this error by pushing a `master` or `main` branch. +:::note -**Note**: Once **semantic-release** is configured, any user with the permission to push commits on one of those branches will be able to publish a release. It is recommended to protect those branches, for example with [GitHub protected branches](https://docs.github.com/github/administering-a-repository/about-protected-branches). +- Branches configuration key accepts [**micromatch**](https://github.com/micromatch/micromatch?tab=readme-ov-file#matching-features) globs. +- If your repository does not have a release branch, then **semantic-release** will fail with an `ERELEASEBRANCHES` error message. If you are using the default configuration, you can fix this error by pushing a `main` or `master` branch. +- Once **semantic-release** is configured, any user with the permission to push commits on one of those branches will be able to publish a release. It is recommended to protect those branches, for example with [GitHub rulesets](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/about-rulesets). -See [Workflow configuration](workflow-configuration.md#workflow-configuration) for more details. +See [Workflow configuration](workflow-#workflow-configuration) for more details. +::: -### repositoryUrl +### `repositoryUrl` -Type: `String`\ -Default: `repository` property in `package.json` or [git origin url](https://git-scm.com/book/en/v2/Git-Basics-Working-with-Remotes)\ -CLI arguments: `-r`, `--repository-url` +**type**: `String`\ +**default**: `repository` property in `package.json` or [git origin url](https://git-scm.com/book/en/v2/Git-Basics-Working-with-Remotes)\ +**CLI arguments**: `-r`, `--repository-url` The git repository URL. Any valid git url format is supported (See [Git protocols](https://git-scm.com/book/en/v2/Git-on-the-Server-The-Protocols)). -### tagFormat +### `tagFormat` -Type: `String`\ -Default: `v${version}`\ -CLI arguments: `-t`, `--tag-format` +**type**: `String`\ +**default**: `v${version}`\ +**CLI arguments**: `-t`, `--tag-format` The [Git tag](https://git-scm.com/book/en/v2/Git-Basics-Tagging) format used by **semantic-release** to identify releases. The tag name is generated with [Lodash template](https://lodash.com/docs#template) and will be compiled with the `version` variable. -**Note**: The `tagFormat` must contain the `version` variable exactly once and compile to a [valid Git reference](https://git-scm.com/docs/git-check-ref-format#_description). +:::note +The `tagFormat` must contain the `version` variable exactly once and compile to a [valid Git reference](https://git-scm.com/docs/git-check-ref-format#_description). +::: -### plugins +### `plugins` -Type: `Array`\ -Default: `['@semantic-release/commit-analyzer', '@semantic-release/release-notes-generator', '@semantic-release/npm', '@semantic-release/github']`\ -CLI arguments: `-p`, `--plugins` +**type**: `Array`\ +**default**: `['@semantic-release/commit-analyzer', '@semantic-release/release-notes-generator', '@semantic-release/npm', '@semantic-release/github']`\ +**CLI arguments**: `-p`, `--plugins` -Define the list of plugins to use. Plugins will run in series, in the order defined, for each [steps](../../#release-steps) if they implement it. +Define the list of plugins to use. Plugins will run in series, in the order defined, for each [release step](/foundation/release-steps/) whose lifecycle hook they implement. Plugins configuration can defined by wrapping the name and an options object in an array. -See [Plugins configuration](plugins.md#plugins) for more details. +:::note +While plugins can be listed by name via the `--plugins` CLI argument, individual plugin options cannot be configured through CLI arguments. If you need to configure plugin options beyond specifying which plugins to use, a [configuration file](#configuration-file) is required. +::: + +See [Plugins](/foundation/plugins/) for more details. -### dryRun +### `dryRun` -Type: `Boolean`\ -Default: `false` if running in a CI environment, `true` otherwise\ -CLI arguments: `-d`, `--dry-run` +**type**: `Boolean`\ +**default**: `false` if running in a CI environment, `true` otherwise\ +**CLI arguments**: `-d`, `--dry-run` -The objective of the dry-run mode is to get a preview of the pending release. Dry-run mode skips the following steps: prepare, publish, addChannel, success and fail. In addition to this it prints the next version and release notes to the console. +The objective of the dry-run mode is to get a preview of the pending release. Dry-run mode skips the following lifecycle hooks: `prepare`, `publish`, `addChannel`, `success`, and `fail`. In addition to this it prints the next version and release notes to the console. -**Note**: The Dry-run mode verifies the repository push permission, even though nothing will be pushed. The verification is done to help user to figure out potential configuration issues. +:::note +The Dry-run mode verifies the repository push permission, even though nothing will be pushed. The verification is done to help user to figure out potential configuration issues. +::: -### ci +### `ci` -Type: `Boolean`\ -Default: `true`\ -CLI arguments: `--ci` / `--no-ci` +**type**: `Boolean`\ +**default**: `true`\ +**CLI arguments**: `--ci` / `--no-ci` Set to `false` to skip Continuous Integration environment verifications. This allows for making releases from a local machine. -**Note**: The CLI arguments `--no-ci` is equivalent to `--ci false`. +:::note +The CLI arguments `--no-ci` is equivalent to `--ci false`. +::: -### debug +### `debug` -Type: `Boolean`\ -Default: `false`\ -CLI argument: `--debug` +**type**: `Boolean`\ +**default**: `false`\ +**CLI arguments**: `--debug` Output debugging information. This can also be enabled by setting the `DEBUG` environment variable to `semantic-release:*`. -**Note**: The `debug` is used only supported via CLI argument. To enable debug mode from the [JS API](../developer-guide/js-api.md#javascript-api) use `require('debug').enable('semantic-release:*')`. +:::note +The `debug` option is only supported via CLI argument. To enable debug mode from the [JS API](/developer-guide/js-api#javascript-api) use `require('debug').enable('semantic-release:*')`. +::: ## Git environment variables @@ -183,11 +205,11 @@ Output debugging information. This can also be enabled by setting the `DEBUG` en ## Existing version tags -**semantic-release** uses [Git tags](https://git-scm.com/book/en/v2/Git-Basics-Tagging) to determine the commits added since the last release. If a release has been published before setting up **semantic-release** you must make sure the most recent commit included in the last published release is in the [release branches](configuration.md#branches) history and is tagged with the version released, formatted according to the [tag format](configuration.md#tagformat) configured (defaults to `vx.y.z`). +**semantic-release** uses [Git tags](https://git-scm.com/book/en/v2/Git-Basics-Tagging) to determine the commits added since the last release. If a release has been published before setting up **semantic-release** you must make sure the most recent commit included in the last published release is in the history of the [release branch(es)](#branches) and is tagged with the version released, formatted according to the [tag format](#tagformat) configured (defaults to `vx.y.z`). If the previous releases were published with [`npm publish`](https://docs.npmjs.com/cli/publish) this should already be the case. -For example, if your release branch is `master`/`main`, the last release published on your project is `1.1.0` and the last commit included has the sha `1234567`, you must make sure this commit is in `master`/`main` history and is tagged with `v1.1.0`. +For example, if your release branch is `main`/`master`, the last release published on your project is `1.1.0` and the last commit included has the sha `1234567`, you must make sure this commit is in `main`/`master` history and is tagged with `v1.1.0`. ```bash # Make sure the commit 1234567 is in the release branch history diff --git a/src/content/docs/usage/getting-started.md b/src/content/docs/usage/getting-started.md deleted file mode 100644 index 0b9b97a..0000000 --- a/src/content/docs/usage/getting-started.md +++ /dev/null @@ -1,10 +0,0 @@ ---- -title: "Getting started" ---- - -In order to use **semantic-release** you must follow these steps: - -1. [Install](installation.md#installation) **semantic-release** in your project -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) diff --git a/src/content/docs/usage/getting-started.mdx b/src/content/docs/usage/getting-started.mdx new file mode 100644 index 0000000..b64da75 --- /dev/null +++ b/src/content/docs/usage/getting-started.mdx @@ -0,0 +1,18 @@ +--- +title: "Getting started" +--- + +import { Steps } from "@astrojs/starlight/components"; + +In order to use **semantic-release** you must follow these steps: + +