From ba715d99659acc61de07d176b7333289a87ef3cb Mon Sep 17 00:00:00 2001 From: Micheal Wilkinson Date: Sat, 21 Mar 2026 00:27:18 +0000 Subject: [PATCH] feat: migrate changelog path to CHANGELOG.md --- AGENTS.md | 197 ++++++++++++++++++++++++++++++ changelog.md => CHANGELOG.md | 1 + README.md | 14 ++- action.yml | 2 +- internal/vociferate/vociferate.go | 4 +- prepare/action.yml | 6 +- publish/action.yml | 4 +- 7 files changed, 214 insertions(+), 14 deletions(-) create mode 100644 AGENTS.md rename changelog.md => CHANGELOG.md (97%) diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..015e9a1 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,197 @@ +# Agent Integration Guide + +This guide is for agentic coding partners that need to integrate the composite actions published by this repository. + +## Source Of Truth + +Pin all action references to a released tag (for example `@v0.2.0`) and keep all vociferate references on the same tag in a workflow. + +Published composite actions: + +- `git.hrafn.xyz/aether/vociferate@v0.2.0` (root action) +- `git.hrafn.xyz/aether/vociferate/prepare@v0.2.0` +- `git.hrafn.xyz/aether/vociferate/publish@v0.2.0` +- `git.hrafn.xyz/aether/vociferate/coverage-badge@v0.2.0` + +## Action Selection Matrix + +Use this when deciding which action to call: + +- Choose `prepare` when you need to update changelog/version files, commit, and push a release tag. +- Choose `publish` when a tag already exists and you need to create or update release notes/assets. +- Choose `coverage-badge` after tests have produced `coverage.out` and you need coverage artefacts uploaded. +- Choose root `vociferate` for direct recommend/prepare logic without commit/tag/push behavior. + +## Preconditions + +Apply these checks before invoking actions: + +- Checkout repository first. +- For prepare/publish flows that depend on tags/history, use full history checkout (`fetch-depth: 0`). +- Use valid credentials in `github.token` (or explicit token input for `publish` when needed). +- Set required vars/secrets for coverage uploads: + - `vars.ARTEFACT_BUCKET_NAME` + - `vars.ARTEFACT_BUCKET_ENDPONT` + - `secrets.ARTEFACT_BUCKET_WRITE_ACCESS_KEY` + - `secrets.ARTEFACT_BUCKET_WRITE_ACCESS_SECRET` +- For externally visible changelog links, set `vars.VOCIFERATE_REPOSITORY_URL` to the server/base URL only. + +## Changelog Format Guidance + +Agents should keep `CHANGELOG.md` in a Keep a Changelog compatible structure because vociferate derives versions and release notes from headings. + +Required conventions: + +- Keep the top-level heading as `# Changelog`. +- Maintain an `## [Unreleased]` section. +- Keep the standard subsections under `Unreleased` in this order: + - `### Breaking` + - `### Added` + - `### Changed` + - `### Removed` + - `### Fixed` +- Record releases with headings like `## [1.2.3] - YYYY-MM-DD`. +- Use bullet entries under subsections (for example `- Added new publish output`). +- Preserve or regenerate bottom reference links (`[Unreleased]: ...`, `[1.2.3]: ...`) instead of mixing inline heading links. + +Semver behavior used by recommendation logic: + +- `Breaking` or `Removed` entries trigger a major bump. +- `Added` entries trigger a minor bump. +- Otherwise recommendation falls back to a patch bump. + +Minimal template: + +```markdown +# Changelog + +## [Unreleased] + +### Breaking + +### Added + +### Changed + +### Removed + +### Fixed +``` + +## Minimal Integration Patterns + +### 1. Prepare Then Publish + +```yaml +jobs: + prepare: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + with: + fetch-depth: 0 + - id: prepare + uses: git.hrafn.xyz/aether/vociferate/prepare@v0.2.0 + + publish: + needs: prepare + uses: aether/vociferate/.gitea/workflows/do-release.yml@v0.2.0 + with: + tag: ${{ needs.prepare.outputs.version }} + secrets: inherit +``` + +### 2. Publish Existing Tag + +```yaml +jobs: + release: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + with: + fetch-depth: 0 + - id: publish + uses: git.hrafn.xyz/aether/vociferate/publish@v0.2.0 + with: + version: v1.2.3 +``` + +### 3. Coverage Badge Publication + +```yaml +jobs: + coverage: + runs-on: ubuntu-latest + env: + AWS_ACCESS_KEY_ID: ${{ secrets.ARTEFACT_BUCKET_WRITE_ACCESS_KEY }} + AWS_SECRET_ACCESS_KEY: ${{ secrets.ARTEFACT_BUCKET_WRITE_ACCESS_SECRET }} + AWS_DEFAULT_REGION: ${{ vars.ARTEFACT_BUCKET_REGION }} + AWS_EC2_METADATA_DISABLED: true + steps: + - uses: actions/checkout@v4 + - name: Run tests with coverage + run: go test -covermode=atomic -coverprofile=coverage.out ./... + - id: badge + uses: git.hrafn.xyz/aether/vociferate/coverage-badge@v0.2.0 + with: + artefact-bucket-name: ${{ vars.ARTEFACT_BUCKET_NAME }} + artefact-bucket-endpoint: ${{ vars.ARTEFACT_BUCKET_ENDPONT }} +``` + +## Inputs And Outputs Cheatsheet + +### prepare + +Common inputs: + +- `version` (optional override) +- `version-file` (optional) +- `version-pattern` (optional) +- `changelog` (optional) + +Primary output: + +- `version` (resolved tag, for example `v1.2.3`) + +### publish + +Common inputs: + +- `token` (optional, defaults to workflow token) +- `version` (optional if running from tag ref) +- `changelog` (optional) + +Primary outputs: + +- `release-id` +- `tag` +- `version` + +### coverage-badge + +Required inputs: + +- `artefact-bucket-name` +- `artefact-bucket-endpoint` + +Useful optional inputs: + +- `coverage-profile` (default `coverage.out`) +- `summary-file` (append markdown summary) + +Primary outputs: + +- `total` +- `report-url` +- `badge-url` + +## Guardrails For Agents + +Use these rules to avoid common automation mistakes: + +- Do not mix action tags in one workflow update. +- Do not assume a release workflow will run from a tag push in all environments; reusable workflow call paths are supported. +- Do not treat `VOCIFERATE_REPOSITORY_URL` as a full repository URL; it must be a base URL. +- Keep displayed URLs protocol-relative (`//`) when writing markdown/browser-facing outputs. +- If a workflow environment does not support `GITHUB_STEP_SUMMARY`, append markdown to a file and print it in a final `Summary` step. diff --git a/changelog.md b/CHANGELOG.md similarity index 97% rename from changelog.md rename to CHANGELOG.md index 769a528..42ad42e 100644 --- a/changelog.md +++ b/CHANGELOG.md @@ -28,6 +28,7 @@ A `### Breaking` section is used in addition to Keep a Changelog's standard sect - Added a project LICENSE file. - Root and prepare actions now read `${{ vars.VOCIFERATE_REPOSITORY_URL }}` and forward it to `VOCIFERATE_REPOSITORY_URL` for repository URL override. - Added a published `coverage-badge` composite action for generating and uploading coverage report/badge artefacts for reuse across repositories. +- Added `AGENTS.md`, an explicit integration guide for agentic coding partners using vociferate composite actions. ### Changed diff --git a/README.md b/README.md index 45fa129..afb110f 100644 --- a/README.md +++ b/README.md @@ -17,7 +17,9 @@ revision. ## Use In Other Repositories Vociferate ships three composite actions covering release preparation, release publication, and coverage badge publishing. -Release tags now exist; pin all action and reusable-workflow references to the same released tag (for example, `@v0.2.0`) instead of `@main`. +Release README now exist; pin all action and reusable-workflow references to the same released tag (for example, `@v0.2.0`) instead of `@main`. + +For agentic coding partners, see [`AGENTS.md`](AGENTS.md) for a direct integration playbook, selection matrix, and copy-paste workflow patterns. ### `prepare` — update files, commit, and push tag @@ -51,7 +53,7 @@ jobs: secrets: inherit ``` -Downloads a prebuilt vociferate binary, runs it to update `changelog.md` and +Downloads a prebuilt vociferate binary, runs it to update `CHANGELOG.md` and `release-version`, then commits those changes to the default branch and pushes the release tag. Does not require Go on the runner. @@ -63,7 +65,7 @@ and `version-pattern`: with: version-file: internal/myapp/version/version.go version-pattern: 'const Version = "([^"]+)"' - git-add-files: changelog.md internal/myapp/version/version.go + git-add-files: CHANGELOG.md internal/myapp/version/version.go ``` `prepare` uses `github.token` internally for authenticated fetch/push operations, @@ -89,7 +91,7 @@ jobs: secrets: inherit ``` -Reads the matching section from `changelog.md` and creates or updates the +Reads the matching section from `CHANGELOG.md` and creates or updates the Gitea/GitHub release with those notes. The `version` input is optional — when omitted it is derived from the current tag ref automatically. @@ -183,7 +185,7 @@ Defaults: - `version-file`: `release-version` - `version-pattern`: `^\s*([^\r\n]+)\s*$` -- `changelog`: `changelog.md` +- `changelog`: `CHANGELOG.md` When no `--version-file` flag is provided, `vociferate` derives the current version from the most recent released section heading in the changelog (`## [x.y.z] - ...`). If no prior releases exist, it defaults to `0.0.0` and recommends `v1.0.0` as the first tag. @@ -203,7 +205,7 @@ just go-test Releases use two workflows: -- `Prepare Release` runs on demand, updates `release-version` and `changelog.md`, commits those changes back to `main`, and pushes the release tag. +- `Prepare Release` runs on demand, updates `release-version` and `CHANGELOG.md`, commits those changes back to `main`, and pushes the release tag. - `Prepare Release` then calls `Do Release` directly via reusable `workflow_call` with the resolved tag. - `Do Release` reads the matching changelog section from that tagged revision, creates or updates the release, and uploads prebuilt binaries. diff --git a/action.yml b/action.yml index 50fdf2e..2107c2e 100644 --- a/action.yml +++ b/action.yml @@ -16,7 +16,7 @@ inputs: changelog: description: Path to changelog file relative to repository root. required: false - default: changelog.md + default: CHANGELOG.md recommend: description: If true, print recommended next release tag. required: false diff --git a/internal/vociferate/vociferate.go b/internal/vociferate/vociferate.go index dbf6d65..d9495fe 100644 --- a/internal/vociferate/vociferate.go +++ b/internal/vociferate/vociferate.go @@ -19,7 +19,7 @@ import ( const ( defaultVersionFile = "release-version" defaultVersionExpr = `^\s*([^\r\n]+)\s*$` - defaultChangelog = "changelog.md" + defaultChangelog = "CHANGELOG.md" defaultUnreleasedTemplate = "### Breaking\n\n### Added\n\n### Changed\n\n### Removed\n\n### Fixed\n" ) @@ -38,7 +38,7 @@ type Options struct { // When empty, a line-oriented default matcher is used. VersionPattern string // Changelog is the path to the changelog file, relative to the repository - // root. When empty, changelog.md is used. + // root. When empty, CHANGELOG.md is used. Changelog string } diff --git a/prepare/action.yml b/prepare/action.yml index 974a2e1..39cfc6c 100644 --- a/prepare/action.yml +++ b/prepare/action.yml @@ -26,7 +26,7 @@ inputs: changelog: description: Path to changelog file relative to repository root. required: false - default: changelog.md + default: CHANGELOG.md git-user-name: description: Name for the release commit author. required: false @@ -38,10 +38,10 @@ inputs: git-add-files: description: > Space-separated list of file paths to stage for the release commit. - Defaults to changelog.md and release-version. Adjust when using a + Defaults to CHANGELOG.md and release-version. Adjust when using a custom version-file. required: false - default: 'changelog.md release-version' + default: 'CHANGELOG.md release-version' outputs: version: diff --git a/publish/action.yml b/publish/action.yml index 9545560..7a73191 100644 --- a/publish/action.yml +++ b/publish/action.yml @@ -20,7 +20,7 @@ inputs: changelog: description: Path to changelog file relative to repository root. required: false - default: changelog.md + default: CHANGELOG.md outputs: release-id: @@ -67,7 +67,7 @@ runs: id: extract-notes shell: bash env: - CHANGELOG: ${{ inputs.changelog != '' && inputs.changelog || 'changelog.md' }} + CHANGELOG: ${{ inputs.changelog != '' && inputs.changelog || 'CHANGELOG.md' }} RELEASE_VERSION: ${{ steps.resolve-version.outputs.version }} RUNNER_TEMP: ${{ runner.temp }} run: |