Prepare deterministic reviewable release PRs from a ReleasePlan

[vitormattos]

Parent: #70
Depends on: #71, #79, #83, #84
Related: #80
Blocks: #73, #75, #81

Goal

Turn a validated ReleasePlan into narrowly scoped, reviewable PR changes without publishing a GitHub Release.

Reusable responsibilities

Using consumer configuration and the validated plan:

• build/use normalized release activity;
• generate the curated changelog section;
• resolve the configured changelog target;
• finalize the selected version;
• update configured release-version files;
• produce exact file changes;
• create/update a generated release PR through the GitHub adapter.

LibreSign consumer mapping

For LibreSign stable releases, the configured release PR changes:

• docs/changelogs/changelog-<major>.md;
• appinfo/info.xml;
• package.json;
• package-lock.json.

Do not use root CHANGELOG.md as the mutable release-history source.

Synchronization of released changelog history back to main is handled by #73 after the stable release PR is finalized. This stage must not create an independent second rendering of the same release entry.

Output artifact: ReleasePreparation v1

This stage consumes ReleasePlan v1 and produces a versioned ReleasePreparation v1 containing at least:

• ReleasePlan id/hash;
• target branch and planning base SHA;
• proposed release version/channel/mode;
• exact allowed file diff/digests;
• changelog section/digest;
• generated branch/PR identity;
• generated PR URL/number when applied;
• expected merge preconditions.

It does not contain a final release SHA before merge.

#73 consumes this artifact and turns the merged/revalidated result into PreparedRelease v1.

PR identity

Generated PRs need deterministic machine-readable identity, for example:

• deterministic branch naming;
• explicit marker in PR body;
• dedicated label where available;
• plan id/version metadata.

Identity is an automation signal, not an authorization mechanism.

Classification/context rules

• merged PR title is the deterministic Conventional Commit/SemVer source;
• internal commit messages do not promote release type;
• labels may refine changelog presentation where explicitly documented (for example security, dependencies, area/platform) but do not determine the version bump;
• GitHub Project Status is planning/workflow state and does not affect changelog/SemVer;
• milestone identifies the release train;
• dependency PRs collapse into one dependency-update entry;
• direct translation activity may produce one translation entry.

When the selected final transition removes a configured development/prerelease suffix, release preparation updates the configured version files to the exact final version from ReleasePlan v1; it must not derive a second version independently.

Human review

The maintainer reviews:

• target branch/ref;
• final version/channel;
• included release activity;
• changelog text;
• exact file diff.

A maintainer may edit the PR. Post-merge automation must re-read/revalidate merged state.

Safety

• dry-run produces exact proposed diff;
• stale plan state stops mutation;
• files outside consumer-configured scope fail the stage;
• generated PR creation is idempotent;
• no direct push to protected release branches.

Acceptance criteria

• deterministic output from the same plan/state;
• configurable file/path mapping;
• translation-only and dependency-only releases work;
• version override is visible and validated;
• generated PR is machine-identifiable;
• tests cover changelog generation, release-file updates and unexpected-file rejection;
• LibreSign mapping targets docs/changelogs/changelog-<major>.md;
• ReleasePreparation v1 schema/fixture is committed and consumed by Finalize the merged stable release and synchronize aggregate changelog history #73.

Definition of done

• production preparation command/use case exists in the PHP tool;
• ReleasePreparation v1 schema and fixtures are committed;
• dry-run and applied PR preparation are covered by business-driven tests;
• generated changes are limited to configured release files;
• security-mode behavior from Define security-release-safe domain and serialization contracts #84 is honored;
• Finalize the merged stable release and synchronize aggregate changelog history #73 can consume the committed preparation artifact without rediscovering preparation state.

[vitormattos]

Completed in LibreCodeCoop/release-tool#4. release:prepare consumes ReleasePlan v1 without recomputing version, produces ReleasePreparation v1, updates only consumer-configured release files, renders deterministic per-major changelog content from the planning commit date, supports security-safe output, exact dry-run snapshots and idempotent GitHub PR publication. Stale plan/target state and manually edited generated branches fail closed. The schema/fixture are committed, and source CLI/PHAR preparation parity is part of the PHAR smoke test. Full QA/REUSE/security CI is green.