Support per-major Keep a Changelog storage as a reusable changelog strategy

[vitormattos]

Parent: #70
Depends on: #78, #82, #83, #84
Blocks: #71, #72, #73, #81

Goal

Provide a reusable changelog strategy that supports one Keep a Changelog file per application major while keeping package/output mapping configurable.

LibreSign is the first consumer. The reusable implementation must not hardcode LibreSign paths.

Design rationale

The per-major strategy is intentional.

Common changelog patterns include:

1. one cumulative root CHANGELOG.md;
2. one history per release line/major, selected for packaging;
3. per-change/news fragments assembled at release time.

LibreSign uses option 2 because several stable lines may be maintained concurrently and should not conflict by editing one cumulative changelog file.

This storage choice does not change the Nextcloud package contract: the built app still receives the selected release-line history as package-root CHANGELOG.md.

Do not derive user-facing release notes by printing raw Git history. Git/PR activity is input data; the rendered changelog remains curated, deterministic release documentation.

Incremental output

Completion of this issue adds the reusable ChangelogPolicy/renderer capability to the PHP tool, with fixtures consumed by #71 and #72.

It must extend the foundation from #82 rather than introduce another changelog script/runtime.

Strategy contract

The strategy receives:

• release version;
• normalized ReleaseActivity;
• consumer changelog configuration;
• current changelog content.

It returns:

• changelog target path;
• generated release section;
• complete updated changelog content;
• validation result.

It does not publish packages itself.

Content convention

Generated files follow Keep a Changelog semantics:

• Added;
• Changed;
• Deprecated;
• Removed;
• Fixed;
• Security.

Only populated categories are emitted.

Raw git history is not a user-facing changelog.

Release activity rules

• PR title is the Conventional Commit source used by version policy;
• changelog text is curated for users;
• direct translation activity may create one translation entry;
• dependency bot PRs collapse into one dependency entry;
• release-housekeeping entries are excluded;
• already-published changes are not duplicated;
• labels/context may improve categorization but never override version policy.

Renderer contract

The changelog is user-facing release documentation, not a dump of Git metadata.

For PR-derived entries:

• start from the merged PR title, not internal commit subjects;
• remove configured stable/backport wrappers such as [stable35] and backport: before rendering;
• parse Conventional Commit prefix/scope for classification;
• render the human title without the feat: / fix(scope): syntax unless retaining it improves meaning;
• retain/link the canonical PR number where the consumer format uses PR references;
• never invent prose beyond deterministic normalization.

Default Keep a Changelog mapping for v1:

• feat → Added;
• fix → Fixed;
• explicit security public entry → Security;
• perf, refactor, docs, build, ci, chore and other releasable maintenance → Changed unless consumer policy excludes that item from presentation;
• dependency updates → one collapsed Changed entry;
• translation activity → one collapsed Changed entry.

A consumer may refine display categorization, but display mapping does not alter SemVer policy.

Ordering inside a category is deterministic (for example PR number or merge order) and covered by tests.

Do not generate category headings with no entries.

Per-major mapping

A consumer can configure a template such as:

docs/changelogs/changelog-{major}.md

For release 15.2.4, the resolved target becomes:

docs/changelogs/changelog-15.md

The reusable strategy only resolves/updates source content. Consumer packaging is handled by integration hooks (#81 for LibreSign).

Branch/history model

For LibreSign:

• the selected stable branch is authoritative for the release currently being prepared;
• its per-major changelog entry is reviewed together with the version-file changes;
• main keeps the aggregate archive of per-major release histories across supported lines;
• after the stable release content is finalized, the exact released changelog section is synchronized back to main as defined by Finalize the merged stable release and synchronize aggregate changelog history #73;
• the aggregate archive on main must never be used to rewrite an older stable's app/package version.

The reusable engine must model release-source and aggregate-history branches explicitly rather than assuming all consumers use the same branch policy.

Migration support

Provide deterministic parsing/splitting helpers or a migration command capable of converting an existing cumulative changelog into per-major files without losing release sections.

Migration must be separately testable and must not be required on every release run.

Public documentation presentation

The app repository release history is the source data for public release-history pages.

For LibreSign:

• selected stable per-major changelog is authoritative for the release being prepared;
• main keeps the aggregate archive after synchronization via Finalize the merged stable release and synchronize aggregate changelog history #73;
• GitHub Release body is a release-specific presentation of finalized data;
• docs.libresign.coop is a browsable public presentation synchronized through Keep LibreSign release history canonical in the app repository #86;
• equivalent release text is never hand-maintained independently in the documentation repository.

Documentation publishing

The strategy may expose generated data/artifacts suitable for synchronization to a documentation repository, but the core release/package process must not depend on that repository.

Acceptance criteria

• path template is configurable;
• generated output follows Keep a Changelog;
• translation-only and dependency-only releases work;
• duplicate release versions are rejected;
• existing release sections are preserved;
• migration preserves historical sections;
• tests cover at least three majors;
• no hardcoded LibreSign repository path exists in reusable domain code.

Definition of done

• reusable ChangelogPolicy/renderer is implemented in the PHP tool;
• per-major path strategy is configurable;
• migration helpers preserve existing history;
• English-only LibreSign policy is covered;
• renderer/security behavior is covered with data providers/fixtures under Define business-driven test architecture and conventions for release-tool #90;
• Plan and validate a selected release with the reusable engine #71/Prepare deterministic reviewable release PRs from a ReleasePlan #72 can use the changelog capability without introducing another renderer or storage convention.

[vitormattos]

Implemented in release-tool. ChangelogPolicy provides configurable per-major paths, deterministic Keep a Changelog rendering, wrapper/Conventional Commit normalization, PR references, collapsed dependency/translation entries, security categorization and duplicate-version rejection. ChangelogMigrator deterministically splits cumulative history; tests cover three majors and preserve existing sections. No LibreSign path is hardcoded in the domain policy.