miel.truyen/nx
1
0
Fork 0
Code Issues Pull Requests Actions 5 Packages Projects Releases Wiki Activity

docs(release): optimize the customize semver recipe

Browse Source
This commit is contained in:
Juri 2024-08-06 22:48:48 +02:00 committed by Juri Strumpflohner
parent c2920a207a
commit 04af849c66
6 changed files with 198 additions and 160 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

48
docs/generated/manifests/menus.json
View File

@ -1922,6 +1922,14 @@
"children": [],
"disableCollapsible": false
},
{
"name": "Customize Conventional Commit Types",
"path": "/recipes/nx-release/customize-conventional-commit-types",
"id": "customize-conventional-commit-types",
"isExternal": false,
"children": [],
"disableCollapsible": false
},
{
"name": "Configure Custom Registries",
"path": "/recipes/nx-release/configure-custom-registries",
@ -1962,14 +1970,6 @@
"children": [],
"disableCollapsible": false
},
{
"name": "Customize Conventional Commit Types",
"path": "/recipes/nx-release/customize-conventional-commit-types",
"id": "customize-conventional-commit-types",
"isExternal": false,
"children": [],
"disableCollapsible": false
},
{
"name": "Configure Changelog Format",
"path": "/recipes/nx-release/configure-changelog-format",
@ -3625,6 +3625,14 @@
"children": [],
"disableCollapsible": false
},
{
"name": "Customize Conventional Commit Types",
"path": "/recipes/nx-release/customize-conventional-commit-types",
"id": "customize-conventional-commit-types",
"isExternal": false,
"children": [],
"disableCollapsible": false
},
{
"name": "Configure Custom Registries",
"path": "/recipes/nx-release/configure-custom-registries",
@ -3665,14 +3673,6 @@
"children": [],
"disableCollapsible": false
},
{
"name": "Customize Conventional Commit Types",
"path": "/recipes/nx-release/customize-conventional-commit-types",
"id": "customize-conventional-commit-types",
"isExternal": false,
"children": [],
"disableCollapsible": false
},
{
"name": "Configure Changelog Format",
"path": "/recipes/nx-release/configure-changelog-format",
@ -3716,6 +3716,14 @@
"children": [],
"disableCollapsible": false
},
{
"name": "Customize Conventional Commit Types",
"path": "/recipes/nx-release/customize-conventional-commit-types",
"id": "customize-conventional-commit-types",
"isExternal": false,
"children": [],
"disableCollapsible": false
},
{
"name": "Configure Custom Registries",
"path": "/recipes/nx-release/configure-custom-registries",
@ -3756,14 +3764,6 @@
"children": [],
"disableCollapsible": false
},
{
"name": "Customize Conventional Commit Types",
"path": "/recipes/nx-release/customize-conventional-commit-types",
"id": "customize-conventional-commit-types",
"isExternal": false,
"children": [],
"disableCollapsible": false
},
{
"name": "Configure Changelog Format",
"path": "/recipes/nx-release/configure-changelog-format",

66
docs/generated/manifests/nx.json
View File

@ -2626,6 +2626,17 @@
"path": "/recipes/nx-release/automatically-version-with-conventional-commits",
"tags": ["nx-release"]
},
{
"id": "customize-conventional-commit-types",
"name": "Customize Conventional Commit Types",
"description": "",
"mediaImage": "",
"file": "shared/recipes/nx-release/customize-conventional-commit-types",
"itemList": [],
"isExternal": false,
"path": "/recipes/nx-release/customize-conventional-commit-types",
"tags": ["nx-release"]
},
{
"id": "configure-custom-registries",
"name": "Configure Custom Registries",
@ -2681,17 +2692,6 @@
"path": "/recipes/nx-release/update-local-registry-setup",
"tags": ["nx-release"]
},
{
"id": "customize-conventional-commit-types",
"name": "Customize Conventional Commit Types",
"description": "",
"mediaImage": "",
"file": "shared/recipes/nx-release/customize-conventional-commit-types",
"itemList": [],
"isExternal": false,
"path": "/recipes/nx-release/customize-conventional-commit-types",
"tags": ["nx-release"]
},
{
"id": "configure-changelog-format",
"name": "Configure Changelog Format",
@ -4961,6 +4961,17 @@
"path": "/recipes/nx-release/automatically-version-with-conventional-commits",
"tags": ["nx-release"]
},
{
"id": "customize-conventional-commit-types",
"name": "Customize Conventional Commit Types",
"description": "",
"mediaImage": "",
"file": "shared/recipes/nx-release/customize-conventional-commit-types",
"itemList": [],
"isExternal": false,
"path": "/recipes/nx-release/customize-conventional-commit-types",
"tags": ["nx-release"]
},
{
"id": "configure-custom-registries",
"name": "Configure Custom Registries",
@ -5016,17 +5027,6 @@
"path": "/recipes/nx-release/update-local-registry-setup",
"tags": ["nx-release"]
},
{
"id": "customize-conventional-commit-types",
"name": "Customize Conventional Commit Types",
"description": "",
"mediaImage": "",
"file": "shared/recipes/nx-release/customize-conventional-commit-types",
"itemList": [],
"isExternal": false,
"path": "/recipes/nx-release/customize-conventional-commit-types",
"tags": ["nx-release"]
},
{
"id": "configure-changelog-format",
"name": "Configure Changelog Format",
@ -5087,6 +5087,17 @@
"path": "/recipes/nx-release/automatically-version-with-conventional-commits",
"tags": ["nx-release"]
},
"/recipes/nx-release/customize-conventional-commit-types": {
"id": "customize-conventional-commit-types",
"name": "Customize Conventional Commit Types",
"description": "",
"mediaImage": "",
"file": "shared/recipes/nx-release/customize-conventional-commit-types",
"itemList": [],
"isExternal": false,
"path": "/recipes/nx-release/customize-conventional-commit-types",
"tags": ["nx-release"]
},
"/recipes/nx-release/configure-custom-registries": {
"id": "configure-custom-registries",
"name": "Configure Custom Registries",
@ -5142,17 +5153,6 @@
"path": "/recipes/nx-release/update-local-registry-setup",
"tags": ["nx-release"]
},
"/recipes/nx-release/customize-conventional-commit-types": {
"id": "customize-conventional-commit-types",
"name": "Customize Conventional Commit Types",
"description": "",
"mediaImage": "",
"file": "shared/recipes/nx-release/customize-conventional-commit-types",
"itemList": [],
"isExternal": false,
"path": "/recipes/nx-release/customize-conventional-commit-types",
"tags": ["nx-release"]
},
"/recipes/nx-release/configure-changelog-format": {
"id": "configure-changelog-format",
"name": "Configure Changelog Format",

14
docs/generated/manifests/tags.json
View File

@ -483,6 +483,13 @@
"name": "Automatically Version with Conventional Commits",
"path": "/recipes/nx-release/automatically-version-with-conventional-commits"
},
{
"description": "",
"file": "shared/recipes/nx-release/customize-conventional-commit-types",
"id": "customize-conventional-commit-types",
"name": "Customize Conventional Commit Types",
"path": "/recipes/nx-release/customize-conventional-commit-types"
},
{
"description": "",
"file": "shared/recipes/nx-release/configure-custom-registries",
@ -518,13 +525,6 @@
"name": "Update Your Local Registry Setup to use Nx Release",
"path": "/recipes/nx-release/update-local-registry-setup"
},
{
"description": "",
"file": "shared/recipes/nx-release/customize-conventional-commit-types",
"id": "customize-conventional-commit-types",
"name": "Customize Conventional Commit Types",
"path": "/recipes/nx-release/customize-conventional-commit-types"
},
{
"description": "",
"file": "shared/recipes/nx-release/configure-changelog-format",

12
docs/map.json
View File

@ -998,6 +998,12 @@
"tags": ["nx-release"],
"file": "shared/recipes/nx-release/automatically-version-with-conventional-commits"
},
{
"name": "Customize Conventional Commit Types",
"id": "customize-conventional-commit-types",
"tags": ["nx-release"],
"file": "shared/recipes/nx-release/customize-conventional-commit-types"
},
{
"name": "Configure Custom Registries",
"id": "configure-custom-registries",
@ -1028,12 +1034,6 @@
"tags": ["nx-release"],
"file": "shared/recipes/nx-release/update-local-registry-setup"
},
{
"name": "Customize Conventional Commit Types",
"id": "customize-conventional-commit-types",
"tags": ["nx-release"],
"file": "shared/recipes/nx-release/customize-conventional-commit-types"
},
{
"name": "Configure Changelog Format",
"id": "configure-changelog-format",

216
docs/shared/recipes/nx-release/customize-conventional-commit-types.md
View File

@ -1,112 +1,150 @@
# Customize Conventional Commit Types
Nx Release can defer to the [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) standard to automatically determine the next version to release. To enable this behavior for versioning, see [Automatically Version with Conventional Commits](/recipes/nx-release/automatically-version-with-conventional-commits).
[Nx release](/features/manage-releases) allows you to leverage the [conventional commits](/recipes/nx-release/automatically-version-with-conventional-commits) standard to automatically determine the next version increment.
This recipe will cover how to customize the types of commits that trigger version bumps, how to customize the version bump for each type, and how to customize the changelog entry for each commit type.
By default, this results in:
## Conventional Commits Usage within Nx Release
The conventional commits configuration is used in two different places within Nx Release - once in the version step for determining the version bump, and once when generating changelogs.
### Determine the Version Bump
When `release.version.conventionalCommits` is `true` in `nx.json`, Nx Release will use the commit messages since the last release to determine the version bump. It will look at the type of each commit and determine the highest version bump from the following list:
- 'feat' -> minor
- 'fix' -> patch
For example, if the git history looks like this:
```
- fix(pkg-1): fix something
- feat(pkg-2): add a new feature
- chore(pkg-3): update docs
- chore(release): 1.0.0
```
then Nx Release will select the `minor` version bump and elect to release version 1.1.0. This is because there is a `feat` commit since the last release of 1.0.0. To customize the version bump for different types of commits, or to trigger a version bump with custom commit types, see the [Configure Commit Types](#configure-commit-types) section below.
- `feat(...)` triggering a minor version bump (`1.?.0`)
- `fix(...)` triggering a patch version bump (`1.?.x`)
- `BREAKING CHANGE` in the footer of the commit message or with an exclamation mark after the commit type (`fix(...)!`) triggers a major version bump (`?.0.0`)
{% callout type="info" title="No changes detected" %}
If Nx Release does not find any relevant commits since the last release, it will skip releasing a new version. This works with [independent releases](/recipes/nx-release/release-projects-independently) as well, allowing for only some projects to be released and some to be skipped.
If Nx Release does not find any relevant commits since the last release, it will skip releasing a new version. This works with [independent releases](/recipes/nx-release/release-projects-independently) as well, allowing for only some projects to be released while others are skipped.
{% /callout %}
#### Breaking Changes and Major Version Bumps
However, you can customize how Nx interprets these conventional commits, for both **versioning** and **changelog** generation.
Major version bumps are triggered by the presence of a `BREAKING CHANGE` in the footer of the commit message or with '!' after the commit type and scope, as specified by the [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) standard. This is regardless of the type or scope of the commit. For example:
## Disable a Commit Type for Versioning and Changelog Generation
```
fix: remove deprecated config properties
BREAKING CHANGE: `settings` and `overrides` keys in config are no longer supported
```
```
fix!: do not trigger a workflow when user submits bad data
```
```
feat(pkg-2)!: redirect users to the new workflow page
```
When Nx Release detects a breaking change, it will bump the major version, regardless of the other commits present in the history. Breaking changes will also appear in their own section of the changelog.
### Generate Changelog Sections
Nx Release will sort changes within changelogs into sections based on the type of commit. By default, `fix`, `feat`, and `perf` commits will be included in the changelog. To customize the headers of changelog sections, include other commit types, or exclude the default commit types, see the [Configure Commit Types](#configure-commit-types) section below.
See the [Nx repo](https://github.com/nrwl/nx/releases) for an example of a changelogs generated with Nx Release.
## Configure Commit Types
Commit types are configured in the `release.conventionalCommits.types` property in `nx.json`:
To disable a commit type, set it to `false`.
```json {% fileName="nx.json" %}
{
"release": {
"conventionalCommits": {
"types": {
// disable the fix type for versioning and in the changelog
"fix": false,
"docs": {
"semverBump": "patch",
"changelog": {
"hidden": false,
"title": "Documentation Changes"
}
},
"perf": {
"semverBump": "none",
// omitting "hidden" will default it to false
"changelog": {
"title": "Performance Improvements"
}
},
"deps": {
"semverBump": "minor",
// omitting "hidden" will default it to false
"changelog": {
"title": "Dependency Updates"
}
},
// unspecified semverBump will default to "patch"
"chore": {
// "changelog.hidden" defaults to true, but setting changelog: false
// is a shortcut for setting "changelog.hidden" to false.
"changelog": false
},
// unspecified semverBump will default to "patch"
"styles": {}
// disable the docs type for versioning and in the changelog
"docs": false,
...
}
}
}
}
```
In this example, the following types are configured:
If you just want to disable a commit type for versioning, but still want it to appear in the changelog, set `semverBump` to `none`.
- The `fix` type has been fully disabled, so `fix` commits will not trigger a version bump and will not be included in the changelog.
- The `docs` type will trigger a `patch` version bump and will have the "Documentation Changes" title in the changelog.
- The `perf` type will NOT trigger a version bump and will have the "Performance Improvements" title in the changelog.
- The `deps` type will trigger a `minor` version bump and will have the "Dependency Updates" title in the changelog.
- The `chore` type will trigger a `patch` version bump, which is the default for if `versionBump` is not specified, and will not be included in the changelog.
- The `styles` type will trigger a `patch` version bump, which is the default for if `versionBump` is not specified, and will be included in the changelog with the corresponding default title.
```json {% fileName="nx.json" %}
{
"release": {
"conventionalCommits": {
"types": {
// disable the docs type for versioning, but still include it in the changelog
"docs": {
"semverBump": "none",
...
},
...
}
}
}
}
```
## Changing the Type of Semver Version Bump
Assume you'd like `docs(...)` commit types to cause a `patch` version bump. You can define that as follows:
```json {% fileName="nx.json" %}
{
"release": {
"conventionalCommits": {
"types": {
"docs": {
"semverBump": "patch",
...
},
}
}
}
}
```
## Renaming the Changelog Section for a Commit Type
To rename the changelog section for a commit type, set the `title` property.
```json {% fileName="nx.json" %}
{
"release": {
"conventionalCommits": {
"types": {
...
"docs": {
...
"changelog": {
"title": "Documentation Changes"
}
},
...
}
}
}
}
```
## Hiding a Commit Type from the Changelog
To hide a commit type from the changelog, set `changelog` to `false`.
```json {% fileName="nx.json" %}
{
"release": {
"conventionalCommits": {
"types": {
...
"chore": {
"changelog": false
},
...
}
}
}
}
```
Alternatively, you can set `hidden` to `true` to achieve the same result.
```json {% fileName="nx.json" %}
{
"release": {
"conventionalCommits": {
"types": {
...
"chore": {
"changelog": {
"hidden": true
}
},
...
}
}
}
}
```
## Defining non-standard Commit Types
If you want to use custom, non-standard conventional commit types, you can define them in the `types` object. If you don't specify a `semverBump`, Nx will default to `patch`.
```json {% fileName="nx.json" %}
{
"release": {
"conventionalCommits": {
"types": {
"awesome": {}
}
}
}
}
```

2
docs/shared/reference/sitemap.md
View File

@ -157,12 +157,12 @@
- [Get Started with Nx Release](/recipes/nx-release/get-started-with-nx-release)
- [Release Projects Independently](/recipes/nx-release/release-projects-independently)
- [Automatically Version with Conventional Commits](/recipes/nx-release/automatically-version-with-conventional-commits)
- [Customize Conventional Commit Types](/recipes/nx-release/customize-conventional-commit-types)
- [Configure Custom Registries](/recipes/nx-release/configure-custom-registries)
- [Publish in CI/CD](/recipes/nx-release/publish-in-ci-cd)
- [Automate GitHub Releases](/recipes/nx-release/automate-github-releases)
- [Publish Rust Crates](/recipes/nx-release/publish-rust-crates)
- [Update Your Local Registry Setup to use Nx Release](/recipes/nx-release/update-local-registry-setup)
- [Customize Conventional Commit Types](/recipes/nx-release/customize-conventional-commit-types)
- [Configure Changelog Format](/recipes/nx-release/configure-changelog-format)
- [Publish a Custom Dist Directory](/recipes/nx-release/publish-custom-dist-directory)
- [Other](/recipes/other)