Publish an adopter-language changelog on the releases page

[sameera]

Each release publishes a changelog on the project's releases page that describes what changed in how a pipeline stage behaves, in adopter language rather than as a list of code changes.

Meta

• feature: docs/features/component-distribution
• estimate: S
• candidate stories: Each release entry describes behaviour changes to pipeline stages in adopter language; The changelog is published on the releases page alongside the tagged release
• source: discovery of "installing Nexus components outside the target repo" (2026-08-16)

Decisions this goal hangs on

Does a repo keep the ability to pin the Nexus component version it runs?

• Decided: A repository keeps no version pin, and no file authored in a target repository names a Nexus version. The review property survives only in a changed form. A component change no longer appears in the adopter's diff, so the changelog becomes the only carrier of what changed in how a pipeline stage behaves. The changelog must therefore describe behaviour changes to stages in adopter language rather than describing code changes. That obligation is load-bearing and is bound work, not release hygiene.
• Why: Under the current arrangement an adopter sees every component change in the repository's own diff, because the components are committed there. Once the components leave every repository, that review surface is gone, and nothing replaces it unless the changelog does. The three failure classes settle how much other mechanism is warranted: a missing verb and an unrecognised configuration key both already fail loudly with a diagnostic, and the one class that fails silently is a change in what a stage decides, which no version check can detect. The changelog is the only thing that can report that class.
• Refuted alternative: Keep a declared version in the repository that the shared install checks itself against, so that the adopter has a version-level signal instead. It loses on who maintains it: a declaration is authored by a human, nobody will bump it, and every repository drifts into a permanent warning that becomes noise within two releases. A version number would also not carry what changed in how a stage decides, which is the information the review surface actually provided.

Which pain must this refactor remove, and who installs Nexus into a repo?

• Decided: Nexus is built for external adopters who never clone the Nexus repository, and Nexus acquires a semantic released version identity, with releases, tags, and a changelog, which gives an adopter a name to install and a version to ask for.
• Why: A person who never clones the Nexus repository has no source checkout to deploy from, so the toolkit must arrive by name and by version, and there is no version identity to pin to today.
• Refuted alternative: Target the single maintainer that the evidence actually shows and drop the released version identity. It loses because it forecloses the adopter, and every property it saves would have to be re-added later.

Through which channel does an external adopter install, update, and remove the Nexus toolkit?

• Decided: The channel is a package on the public npm registry, and the changelog lives on the project's releases page.
• Why: The one dimension where the registry is weaker than a self-served channel is the changelog surface, and it is not a real loss because the two are not exclusive. Nexus lives in a git repository whichever channel installs it, so the releases page hosts the changelog while the registry serves the install. Giving the changelog a purpose-built home is part of meeting the obligation above rather than a concession.
• Refuted alternative: A release asset fetched by an installer script wins on changelog placement, and that win is available to the registry option anyway by publishing the changelog on the releases page. It loses on the three counts that decide the channel: the self-hosted version index needed to hold an older version, the removal manifest it must maintain, and the shell startup file edit it must make and later reverse.

[sameera]

Decisions this goal hangs on

Does a repo keep the ability to pin the Nexus component version it runs?

• Decided: A repository keeps no version pin, and no file authored in a target repository names a Nexus version. The review property survives only in a changed form. A component change no longer appears in the adopter's diff, so the changelog becomes the only carrier of what changed in how a pipeline stage behaves. The changelog must therefore describe behaviour changes to stages in adopter language rather than describing code changes. That obligation is load-bearing and is bound work, not release hygiene.
• Why: Under the current arrangement an adopter sees every component change in the repository's own diff, because the components are committed there. Once the components leave every repository, that review surface is gone, and nothing replaces it unless the changelog does. The three failure classes settle how much other mechanism is warranted: a missing verb and an unrecognised configuration key both already fail loudly with a diagnostic, and the one class that fails silently is a change in what a stage decides, which no version check can detect. The changelog is the only thing that can report that class.
• Refuted alternative: Keep a declared version in the repository that the shared install checks itself against, so that the adopter has a version-level signal instead. It loses on who maintains it: a declaration is authored by a human, nobody will bump it, and every repository drifts into a permanent warning that becomes noise within two releases. A version number would also not carry what changed in how a stage decides, which is the information the review surface actually provided.

Which pain must this refactor remove, and who installs Nexus into a repo?

• Decided: Nexus is built for external adopters who never clone the Nexus repository, and Nexus acquires a semantic released version identity, with releases, tags, and a changelog, which gives an adopter a name to install and a version to ask for.
• Why: A person who never clones the Nexus repository has no source checkout to deploy from, so the toolkit must arrive by name and by version, and there is no version identity to pin to today.
• Refuted alternative: Target the single maintainer that the evidence actually shows and drop the released version identity. It loses because it forecloses the adopter, and every property it saves would have to be re-added later.

Through which channel does an external adopter install, update, and remove the Nexus toolkit?

• Decided: The channel is a package on the public npm registry, and the changelog lives on the project's releases page.
• Why: The one dimension where the registry is weaker than a self-served channel is the changelog surface, and it is not a real loss because the two are not exclusive. Nexus lives in a git repository whichever channel installs it, so the releases page hosts the changelog while the registry serves the install. Giving the changelog a purpose-built home is part of meeting the obligation above rather than a concession.
• Refuted alternative: A release asset fetched by an installer script wins on changelog placement, and that win is available to the registry option anyway by publishing the changelog on the releases page. It loses on the three counts that decide the channel: the self-hosted version index needed to hold an older version, the removal manifest it must maintain, and the shell startup file edit it must make and later reverse.