feat(release): revamped nx release version implementation

[JamesHenry]

This PR provides a new implementation for the versioning stage of nx release which brings a ton of benefits.

Previously unsupported/impossible features now available:

• It is possible to have dependencies which flow across release group boundaries, therefore updateDependents will work across group boundaries as well.
• It is possible to update multiple manifests (such as package.json) for a single versioning execution. For example, updating the version and dependencies in both your source and dist package.json for a project.

Massively improved extensibility for non-JS languages/ecosystems:

• The ReleaseVersionGenerator abstraction was distinctly suboptimal because it required each plugin to reimplement a bunch of core business logic related to resolving tags from git, combining current versions and specifiers to produce new semver values, deleting version plans after use etc.
  • It is now been replaced by the VersionActions class, which exclusively deals with the aspects that make that language/ecosystem unique, such as reading and writing from a manifest file (such as package.json/Cargo.toml etc) if applicable, reading from a remote registry etc.
  • No core business logic about releases is handled within a VersionActions implementation.
  • You can check out the implementation for JS projects here: packages/js/src/generators/release-version/version-actions.ts

Other benefits:

• More performant
• Much better IDE experience for version configuration because of the untyped generatorOptions going away, and most options moving to the top level of release.version config in nx.json.
• More informative logs during versioning, e.g.
  • BEFORE: Resolved the specifier as "minor" using version plans.
  • AFTER: Applied semver relative bump "minor", read from version plan .nx/version-plans/bump-mixed1.md, to get new version 0.2.0
• Lays the groundwork for application releases becoming a first-class use-case as part of our 2025 Roadmap.
• preserveLocalDependencyProtocols is now true by default and can be omitted from end user configs.

---

Notes on rollout

• In Nx v20, it is opt-in via setting "useLegacyVersioning": false in release.version in nx.json.
• It will be enabled by default in Nx v21, with opt-out still possible via setting the flag explicitly to true.
• We will provide an automated migration to the new configuration as part of Nx v21
• The legacy versioning can now be considered "frozen". Some bugs should be fixed by moving to the new versioning, and any future fixes will be applied there.
• In Nx v22, the legacy versioning will be entirely removed.
• Documentation updates will take place in a follow up PR which documents both approaches, whilst making it clear that the legacy versioning is being replaced.

---

You can see how straightforward it was to manually apply using the PR release from this branch on a real world project here: angular-eslint/angular-eslint#2329

---

Fixes #21458
Fixes #21466
Fixes #26444
Fixes #27823
Fixes #28049
Fixes #28695
Fixes #30363

[vercel]

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Updated (UTC)
nx-dev	✅ Ready (Inspect)	Visit Preview	Apr 8, 2025 0:56am

[nx-cloud]

View your CI Pipeline Execution ↗ for commit 15a27dc.

Command	Status	Duration	Result
nx affected --targets=lint,test,build,e2e,e2e-c...	✅ Succeeded	5m 44s	View ↗
nx run-many -t check-imports check-commit check...	✅ Succeeded	19s	View ↗
nx-cloud record -- nx format:check --base=2fd96...	✅ Succeeded	4s	View ↗
nx-cloud record -- nx-cloud conformance:check	✅ Succeeded	3s	View ↗
nx-cloud record -- nx sync:check	✅ Succeeded	<1s	View ↗
nx documentation	✅ Succeeded	<1s	View ↗

---

☁️ Nx Cloud last updated this comment at 2025-04-08 14:00:57 UTC

[FrozenPandaz]

nit: not a fan of this method name. Is postVersioning callback a better name?

[JamesHenry]

It is now an exported function as discussed. I couldn't help feeling like afterAllProjectsVersioned is a clearer name because it's not after all of the version logic runs (it's before git for example), so postVersion felt a little ambiguous

[JamesHenry]

But I have indeed been able to flatten it now too and avoid the higher order function

[github-actions]

🐳 We have a release for that!

This PR has a release associated with it. You can try it out using this command:

npx [email protected] my-workspace

Or just copy this version and use it in your own command:

0.0.0-pr-30418-80f02f7

Release details	📑
Published version	0.0.0-pr-30418-80f02f7
Triggered by	@JamesHenry
Branch	nx-release-v-v2
Commit	80f02f7
Workflow run	14115494427

To request a new release for this pull request, mention someone from the Nx team or the @nrwl/nx-pipelines-reviewers.

[github-actions]

🐳 We have a release for that!

This PR has a release associated with it. You can try it out using this command:

npx [email protected] my-workspace

Or just copy this version and use it in your own command:

0.0.0-pr-30418-6fbe6c1

Release details	📑
Published version	0.0.0-pr-30418-6fbe6c1
Triggered by	@JamesHenry
Branch	nx-release-v-v2
Commit	6fbe6c1
Workflow run	14135844180

To request a new release for this pull request, mention someone from the Nx team or the @nrwl/nx-pipelines-reviewers.

[CatsMiaow]

hello.
Could this PR also provide a setting to add a force option to gitPush? Maybe by adding a gitPushArgs option?

The above error can be solved with force push, but there is no push option provided.

nx/packages/nx/src/command-line/release/utils/git.ts

Lines 424 to 432 in 6e50a01

	const commandArgs = [
	'push',
	// NOTE: It's important we use --follow-tags, and not --tags, so that we are precise about what we are pushing
	'--follow-tags',
	'--no-verify',
	'--atomic',
	// Set custom git remote if provided
	...(gitRemote ? [gitRemote] : []),
	];

Scripted, it would look like this
Currently, we have the gitCommitArgs and gitTagsArgs options, but not the gitPushArgs option.

import { releaseVersion } from 'nx/release';

const version = await releaseVersion({
  verbose: true,
  gitTag: true,
  gitTagArgs: [],
  gitCommit: true,
  gitCommitArgs: [],
  gitPush: true,
  gitPushArgs: ['-f'], // or gitPushForce: true
  gitRemote: 'origin',
  firstRelease: true,
});

[github-actions]

🐳 We have a release for that!

This PR has a release associated with it. You can try it out using this command:

npx [email protected] my-workspace

Or just copy this version and use it in your own command:

0.0.0-pr-30418-d6cd6b6

Release details	📑
Published version	0.0.0-pr-30418-d6cd6b6
Triggered by	@JamesHenry
Branch	nx-release-v-v2
Commit	d6cd6b6
Workflow run	14333346914

To request a new release for this pull request, mention someone from the Nx team or the @nrwl/nx-pipelines-reviewers.

[github-actions]

This pull request has already been merged/closed. If you experience issues related to these changes, please open a new issue referencing this pull request.