Plan and apply reusable release milestone transitions

[vitormattos]

Parent: #70
Depends on: #73, #80, #83
Blocks: #75, #76

Goal

Consume a finalized PreparedRelease v1 and apply milestone rotation as a deterministic reusable policy/application stage.

Consumer configuration provides milestone naming conventions. LibreSign is the first configured consumer.

Input artifact

This stage consumes PreparedRelease v1.

It must not run the mutating milestone transition from a pre-merge ReleasePlan alone.

A pure policy/planning component may be unit-tested earlier, but application happens only after #73 has produced the final release SHA/state.

Normal stable policy for LibreSign

A stable line normally has a Next Patch (XX) milestone. In the Talk-style convention, Next Patch (XX) tracks the next dot release for that Nextcloud line, while a separate Next Major (XX)/equivalent milestone may represent feature work for the next larger line. The exact names remain consumer configuration.

For a release:

1. identify current milestone;
2. rename it to release version;
3. optionally create next milestone;
4. move remaining open issues/PRs to follow-up milestone;
5. close released milestone.

The maintainer explicitly decides whether a follow-up milestone is created. Do not infer EOL automatically.

Lifecycle/EOL data can be context only.

Prereleases

Alpha/beta/RC may use a different milestone sequence.

Keep milestone policy compatible with #80 and configurable rather than hardcoding all channels as Next Patch.

Ordering

Milestone transition occurs after the release preparation PR is merged/revalidated and before the final GitHub Release draft is considered ready for publication.

A milestone transition does not consume or increment the planned release version.

If a correction is needed before successful publication, the same planned version remains valid unless explicitly changed.

Dry-run

Before mutation output exact operations:

• milestone rename;
• follow-up milestone creation;
• issues to move;
• PRs to move;
• milestone closure.

Idempotency

Rerun after partial/full transition must converge safely or stop with precise non-destructive diagnostics.

Output artifact: MilestoneTransition v1

Return a versioned MilestoneTransition v1 bound to the PreparedRelease v1 id/hash.

It contains at least:

• released milestone number/id;
• released milestone URL;
• final title;
• follow-up milestone id/url if created;
• moved item counts.

These outputs feed #75.

Acceptance criteria

• plan/apply separated;
• consumer naming configurable;
• all mutations visible before apply;
• final-stable/no-follow-up path tested;
• prerelease strategy tested;
• reruns safe;
• closed milestone URL available to release draft;
• MilestoneTransition v1 schema/fixture is committed and consumed by Prepare the GitHub Release draft from finalized release artifacts #75.

Definition of done

• milestone plan/apply behavior is implemented in the PHP tool;
• MilestoneTransition v1 schema and fixtures are committed;
• normal, prerelease, no-follow-up and rerun scenarios are covered by business-driven tests;
• mutations are idempotent or fail with actionable diagnostics;
• Prepare the GitHub Release draft from finalized release artifacts #75 can consume the milestone artifact directly.

[vitormattos]

Completed in LibreCodeCoop/release-tool#8. milestone:transition now consumes PreparedRelease v1, plans exact rename/follow-up/item-move/close operations before mutation, applies them through the GitHub API, supports configured stable and prerelease milestone names, explicit no-follow-up flows, and recognizes completed reruns safely. MilestoneTransition v1 schema/fixture/codec is committed, the closed released milestone URL is carried forward for #75, and the full PHP/PHAR/static-analysis/Infection/REUSE/workflow CI is green.