105 lines
3.2 KiB
Markdown
105 lines
3.2 KiB
Markdown
# 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
|