Nx Release: Difficulty Graduating SNAPSHOT Versions to Stable with Correct Changelog History

[SteveFoxx]

Our team employs a staged release strategy where we utilize -SNAPSHOT.X suffixed versions for internal testing and validation before publishing official, stable releases. For instance, a component might evolve from a stable 1.0.0 to an internal 1.1.0-SNAPSHOT.1 after a pre-minor increment.

The core difficulty emerges when we decide to 'graduate' these SNAPSHOT versions to their corresponding stable releases (e.g., promoting 1.1.0-SNAPSHOT.1 to 1.1.0). We encounter significant friction due to limitations in the existing Nx release tooling:
Lack of a Streamlined Promotion Path: There isn't a straightforward, dedicated mechanism within Nx to formally transition a -SNAPSHOT.X version to its stable, non-suffixed equivalent. This means the process of declaring a SNAPSHOT "ready for stable release" and adjusting its version identifier accordingly feels like a manual step rather than a supported workflow.
Fragmented or Incomplete Changelog Generation: This is the most critical pain point. When attempting to generate changelogs for the new stable release (e.g., 1.1.0), the default behavior of the tooling tends to create a changelog based on the delta from the most recent tag, which would be the last SNAPSHOT tag (e.g., 1.1.0-SNAPSHOT.1).

This results in changelogs for stable releases that only reflect changes made since the last internal SNAPSHOT, rather than providing a comprehensive overview of all changes accumulated since the previous stable release (e.g., from 1.0.0 to 1.1.0).
Consequently, the official release notes for stable versions lack the full historical context that users upgrading from a previous stable version would expect.

Manual Reconciliation and Overhead: Due to these limitations, we are forced into manual workarounds:

We either have to meticulously track commits across multiple SNAPSHOT iterations ourselves to manually compile a complete changelog for the stable release.

Alternatively, if we rely on the default automated changelog generation, we accept that our stable release changelogs are incomplete or misleading, as they don't capture the entire scope of changes between stable milestones.

In essence, while our SNAPSHOT-based internal release process allows for valuable iteration and testing, the current tooling capabilities create a disconnect and significant manual effort when bridging the gap between these internal versions and the final, user-facing stable releases, particularly concerning accurate and comprehensive version history and changelog documentation.