sow-tools/CHANGELOG_AUTOMATION_CONTRACT.md

Changelog Automation Contract

Status Snapshot

Current state as of 2026-05-13:

• The shared implementation is present in internal/changelog/ and is exposed as sow-toolkit build-changelog.
• Consumer configs exist in both module/scripts/changelog.json and assets/scripts/changelog.json.
• CLI parsing and generator behavior are covered by internal/app/app_test.go and internal/changelog/changelog_test.go.
• module/scripts/release-all.sh already stages build/CHANGELOG.md.

Remaining work:

• confirm and document the assets/ release workflow uses the shared command in the same way as module/
• build the deferred cross-repo NodeBB aggregation bot if combined public release posts are still desired

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:

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 and commit 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 support both first-parent pull-request-style pushes and direct first-parent pushes between the selected tags.

For pull-request-style commits that include a (#123) suffix, the generator must resolve 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.

For direct pushes without a pull number suffix, the generator must render the commit using its commit hash link and commit author without calling the pull request API.

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 one of these forms:

- Title ([#123](.../pulls/123)) - From Author Name
- Title ([abc1234](.../commit/<sha>)) - 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