feat: migrate changelog path to CHANGELOG.md

2026-03-21 00:27:18 +00:00
parent 62f637614d
commit ba715d9965
7 changed files with 214 additions and 14 deletions
--- a/AGENTS.md
+++ 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.
--- 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

--- 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.

--- 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
--- 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
 }

--- 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:
--- 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: |