Changelog Automation

2026-05-06 13:51:00 +02:00
parent a7b4c4a908
commit 90ba281f1b
4 changed files with 698 additions and 0 deletions
@@ -0,0 +1,104 @@
+# Changelog Automation Contract
+
+## Scope
+
+This contract governs release changelog generation across:
+
+- `toolkit/` as the implementation owner
+- `module/` as a changelog-producing consumer
+- `assets/` as a changelog-producing consumer
+
+The immediate goal is to produce stable per-repo `CHANGELOG.md` release artifacts
+that can later be merged by a NodeBB bot into one combined release post.
+
+## Ownership Split
+
+- `toolkit/`
+  - owns the shared changelog generator implementation
+  - owns the CLI contract exposed through `sow-toolkit`
+  - owns the config schema used by consumer repos
+- `module/`
+  - owns its changelog section mapping under `scripts/changelog.json`
+  - owns invoking changelog generation during its tag release flow
+- `assets/`
+  - owns its changelog section mapping under `scripts/changelog.json`
+  - owns invoking changelog generation during its tag release flow
+
+## Shared CLI Contract
+
+The canonical generator entrypoint is:
+
+```bash
+sow-toolkit build-changelog
+```
+
+Supported flags:
+
+- `--config <path>`: repo-local JSON section config
+- `--output <path>`: write rendered Markdown to a file; otherwise stdout
+- `--current-tag <tag>`: optional explicit current tag
+- `--previous-tag <tag>`: optional explicit previous tag
+- `--api-base-url <url>`: optional explicit Gitea API base URL
+- `--token <token>`: optional explicit Gitea API token
+
+If `--current-tag` is omitted, the generator must resolve the exact tag at
+`HEAD`. If `--previous-tag` is omitted, it must select the next older tag by
+`creatordate`.
+
+## Config Contract
+
+Each consumer repo provides `scripts/changelog.json` with:
+
+- `repo_url`: canonical web URL for pull request links
+- `categories[]`
+- `categories[].title`
+- `categories[].sections[]`
+- `categories[].sections[].title`
+- `categories[].sections[].paths[]`
+
+Paths are repo-relative path filters passed through to `git log`.
+
+## Author Contract
+
+Rendered changelog entries must resolve pull request author names from the
+Gitea pull request API rather than trusting the merge commit author field.
+
+Expected endpoint shape:
+
+- `GET /api/v1/repos/{owner}/{repo}/pulls/{index}`
+- prefer `user.full_name`
+- fall back to `user.login` only if `full_name` is empty
+
+## Release Contract
+
+For each version-tagged release workflow:
+
+1. generate `build/CHANGELOG.md` for the current tag;
+2. upload `CHANGELOG.md` as a release asset on the versioned release;
+3. keep the file name stable across repos so later automation can fetch it
+   without repo-specific asset naming logic.
+
+The changelog is a staged build artifact, not a committed source-controlled file.
+This avoids detached-tag push complexity while preserving a stable artifact for
+later aggregation.
+
+## Output Contract
+
+The Markdown output must remain simple and merge-friendly:
+
+- title line with current tag and publish date
+- comparison line naming the previous tag when one exists
+- category headings
+- section headings
+- bullet entries in the form:
+
+```text
+- Title ([#123](.../pulls/123)) - From Author Name
+```
+
+## Deferred Work
+
+- add a dedicated bot that fetches `CHANGELOG.md` assets from module and assets
+  releases, merges them, and publishes a single NodeBB release post
+- decide whether changelog generation should later move from shell wrappers into
+  first-class repo-root user commands