-
Notifications
You must be signed in to change notification settings - Fork 2.4k
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
docs(release): file based versioning, version plans (#27428)
<!-- Please make sure you have read the submission guidelines before posting an PR --> <!-- https://github.com/nrwl/nx/blob/master/CONTRIBUTING.md#-submitting-a-pr --> <!-- Please make sure that your commit message follows our format --> <!-- Example: `fix(nx): must begin with lowercase` --> <!-- If this is a particularly complex change or feature addition, you can request a dedicated Nx release for this pull request branch. Mention someone from the Nx team or the `@nrwl/nx-pipelines-reviewers` and they will confirm if the PR warrants its own release for testing purposes, and generate it for you if appropriate. --> ## Current Behavior <!-- This is the behavior we have today --> Version plans, stable in the imminent `19.6.0` release, is undocumented. ## Expected Behavior <!-- This is the behavior we should expect with the changes in this PR --> Version plans is a documented feature. ## Related Issue(s) <!-- Please link the issue being fixed so it gets closed when this is merged. --> Fixes # --------- Co-authored-by: Isaac Mann <[email protected]> (cherry picked from commit f1ecad0)
- Loading branch information
1 parent
f4c93ff
commit 706a13f
Showing
6 changed files
with
191 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
120 changes: 120 additions & 0 deletions
120
docs/shared/recipes/nx-release/file-based-versioning-version-plans.md
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,120 @@ | ||
| # File Based Versioning ("Version Plans") | ||
|
|
||
| Tools such as Changesets and Beachball helped popularize the concept of tracking the desired semver version bump in a separate file on disk (which is committed to your repository alongside your code changes). This has the advantage of separating the desired bump from your git commits themselves, which can be very useful if you are not able to enforce that all contributors follow a strict commit message format ([e.g. Conventional Commits](/recipes/nx-release/automatically-version-with-conventional-commits)), or if you want multiple commits to be included in the same version bump and therefore not map commits 1:1 with changelog entries. | ||
|
|
||
| Nx release supports file based versioning as a first class use-case through a feature called "version plans". The idea behind the name is that you are creating a _plan_ to version; a plan which will be _applied_ sometime in the future when you actually invoke the `nx release` CLI or programmatic API. Therefore you can think about version plans as having two main processes: creating version plans and applying version plans. We will cover both in this recipe, but first we need to enable the feature itself. | ||
|
|
||
| ## Enable Version Plans | ||
|
|
||
| To enable version plans as a feature in your workspace, set `release.versionPlans` to `true` in `nx.json`: | ||
|
|
||
| ```jsonc | ||
| { | ||
| "release": { | ||
| "versionPlans": true | ||
| // other release config such as projects to include in releases etc | ||
| // projects: ["packages/**/*"] | ||
| // ... | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| You can also enable or disable this for specific release groups by setting the property at the group level if you don't want to apply it to all matching projects in your workspace. | ||
|
|
||
| ## Create Version Plans | ||
|
|
||
| Version plan files live in the `.nx/version-plans/` directory within your workspace (which needs to be tracked by git, so ensure that you are not ignoring the whole `.nx` directory, and instead only the `.nx/workspace-data` and `.nx/cache` directories). | ||
|
|
||
| The files themselves are written in markdown (`.md` files) and contain Front Matter YAML metadata at the top of the file. The Front Matter YAML section is denoted via triple dashes `---` at the start and end of the section. For example: | ||
|
|
||
| ```md {% fileName=".nx/version-plans/version-plan-1723732065047.md" %} | ||
| --- | ||
| # | ||
| # FRONT MATTER YAML HERE | ||
| # | ||
| --- | ||
|
|
||
| # | ||
|
|
||
| # Regular markdown here | ||
|
|
||
| # | ||
| ``` | ||
|
|
||
| We leverage the Front Matter YAML section to store a mapping of project or release group names to desired semver bump types. The general markdown section represents the description of the change(s) made that will be used in any relevant `CHANGELOG.md` files that are generated later at release time. | ||
|
|
||
| For example, the following Front Matter YAML section specifies that the `my-app` project should have a `minor` version bump and describes the changes (again, note that there are no constraints on the format of the description, it can contain multiple lines, paragraphs etc): | ||
|
|
||
| ```md {% fileName=".nx/version-plans/version-plan-1723732065047.md" %} | ||
| --- | ||
| my-app: minor | ||
| --- | ||
|
|
||
| This is an awesome change! | ||
|
|
||
| A new paragraph describing the change in greater detail. All of this will be included in the CHANGELOG.md. All of this structure within the markdown section is optional and flexible. | ||
| ``` | ||
|
|
||
| Any number of different projects and different desired semver bumps can be combined within a single version plan file (which represents one change and therefore changelog entry, if applicable). For example: | ||
|
|
||
| ```md {% fileName=".nx/version-plans/version-plan-1723732065047.md" %} | ||
| --- | ||
| my-app: minor | ||
| my-lib: patch | ||
| release-group-a: major | ||
| --- | ||
|
|
||
| One change that affects multiple projects and release groups. | ||
| ``` | ||
|
|
||
| The project or release group names specified in the Front Matter YAML section must match the names of the projects and/or release groups in your workspace. If a project or release group is not found, an error will be thrown when applying the version plan as part of running `nx release`. | ||
|
|
||
| Because these are just files, they can be created manually or by any custom scripts you may wish to write. They simply have to follow the guidance above around structure, location (`./.nx/version-plans/`) and naming (`.md` extension). The exact file name does not matter, it just needs to be unique within the `.nx/version-plans/` directory. | ||
|
|
||
| To make things easier, Nx release comes with a built in command to help you generate valid version plan files: | ||
|
|
||
| ```sh | ||
| nx release plan | ||
| ``` | ||
|
|
||
| When you run this command you will receive a series of interactive prompts which guide you through the process of creating a version plan file. It will generate a unique name for you and ensure it is written to the correct location. | ||
|
|
||
| ## Apply Version Plans at Release Time | ||
|
|
||
| Using version plans does not change how versioning, changelog generation and publishing is invoked, you can still use the `nx release` CLI or programmatic API as you would for any other versioning strategy. | ||
|
|
||
| The only difference is that Nx release will know to reference your version plan files as the source of truth for the desired version bumps. You still retain the same control around resolving the current version (disk vs registry vs git tags) however you want, and other configuration options around things like git operations are all still applicable. | ||
|
|
||
| When you run `nx release` or use the programmatic API, Nx will look for version plan files in the `.nx/version-plans/` directory and apply the desired version bumps to the projects and release groups specified in the Front Matter YAML section of each file. If a project or release group is not found, an error will be thrown and the release will not proceed. Once a particular version plan has been applied it will be deleted from the `.nx/version-plans/` directory so that it does not inadvertently get applied again in the future. The deleted file will be staged and committed alongside your other changed files that were modified directly as part of the release command (depending on your Nx release configuration). | ||
|
|
||
| ## Ensure That Version Plans Exist for Relevant Changes | ||
|
|
||
| When making changes to your codebase and using version plans as your versioning strategy it is likely that you will want to ensure that a version plan file exists for the changes you are making. | ||
|
|
||
| Attempting to keep track of this manually as a part of pull request reviews can be error prone and time consuming, therefore Nx release provides a `nx release plan:check` command which can be used to ensure that a version plan file exists for the changes you are making. | ||
|
|
||
| ```sh | ||
| nx release plan:check | ||
| ``` | ||
|
|
||
| Running this command will analyze the changed files (supporting the same options you may be familiar with from `nx affected`, such as `--base`, `--head`, `--files`, `--uncommitted`, etc) and then determine which projects have been "touched" as a result. Note that it is specifically touched projects, and not affected in this case, because only directly changed projects are relevant for versioning. The side-effects of versioning independently released dependents are handled by the release process itself (controllable via the `version.generatorOptions.updatedDependents` option). | ||
|
|
||
| Nx release will compare the touched projects to the projects and release groups that are specified in the version plan files in the `.nx/version-plans/` directory. If a version plan file does not exist, the command will print an error message and return a non-zero exit code, which can be used to fail CI builds or other automation. | ||
|
|
||
| By default, all files that have changed are considered, but you may not want all files under a project to require a version plan be created for them. For example, you may wish to ignore test only files from consideration from this check. The way you can achieve this is by setting version plans to be a configuration object instead of a boolean, and set the `"ignorePatternsForPlanCheck"` property to an array of glob patterns that should be ignored when checking for version plans. For example: | ||
|
|
||
| ````jsonc | ||
| { | ||
| "release": { | ||
| "versionPlans": { | ||
| "ignorePatternsForPlanCheck": ["**/*.spec.ts"] | ||
| } | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| To see more details about the changed files that were detected and the filtering logic that was used to determine the ultimately changed projects behind the scenes, you can pass `--verbose` to the command: | ||
|
|
||
| ```sh | ||
| nx release plan:check --verbose | ||
| ```` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters