diff --git a/README.md b/README.md index b077614..36e6c26 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,118 @@ # vociferate -A reusable release preparation tool for Go repositories. +`vociferate` is a release orchestration tool written in Go for repositories that +want changelog-driven versioning, automated release preparation, and repeatable +tag publication. + +It started as release preparation glue, but it now covers the full release path: +recommend the next semantic version, promote `Unreleased` changelog entries, +commit and tag a release, and publish release notes/assets from the tagged +revision. + +## Reuse In Other Repositories + +Vociferate ships two composite actions that together cover the full release flow. +Pin both to the same released tag. + +### `prepare` — update files, commit, and push tag + +```yaml +name: Prepare Release + +on: + workflow_dispatch: + inputs: + version: + description: Optional semantic version override. + required: false + +jobs: + prepare: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + with: + fetch-depth: 0 + + - name: Resolve cache token + id: cache-token + run: echo "value=${GITHUB_SHA}" >> "$GITHUB_OUTPUT" + + - uses: git.hrafn.xyz/aether/vociferate/prepare@v1.0.0 + env: + VOCIFERATE_CACHE_TOKEN: ${{ steps.cache-token.outputs.value }} + with: + version: ${{ inputs.version }} +``` + +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. + +For repositories that embed the version inside source code, pass `version-file` +and `version-pattern`: + +```yaml +- uses: git.hrafn.xyz/aether/vociferate/prepare@v1.0.0 + env: + VOCIFERATE_CACHE_TOKEN: ${{ github.sha }} + with: + version-file: internal/myapp/version/version.go + version-pattern: 'const Version = "([^"]+)"' + git-add-files: changelog.md internal/myapp/version/version.go +``` + +`prepare` uses `github.token` internally for authenticated fetch/push operations, +so no token input is required. + +### `publish` — create release with changelog notes + +```yaml +name: Do Release + +on: + push: + tags: + - "v*.*.*" + +jobs: + release: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + + - uses: git.hrafn.xyz/aether/vociferate/publish@v1.0.0 +``` + +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. + +The `publish` action outputs `release-id` so you can upload additional release +assets after it runs: + +```yaml +- id: publish + uses: git.hrafn.xyz/aether/vociferate/publish@v1.0.0 + +- name: Upload my binary + run: | + curl --fail-with-body -X POST \ + -H "Authorization: token ${{ secrets.GITHUB_TOKEN }}" \ + -H "Content-Type: application/octet-stream" \ + "${{ github.api_url }}/repos/${{ github.repository }}/releases/${{ steps.publish.outputs.release-id }}/assets?name=myapp" \ + --data-binary "@dist/myapp" +``` + +## Why The Name + +> **vociferate** _(verb)_: to cry out loudly or forcefully. + +Long story short: vociferating into the Æther is synonymous screaming into the +void. + +If updating changelogs and documenting releases has ever felt like that, this +tool is for you. ## Build @@ -78,93 +190,3 @@ The tag-driven `Do Release` workflow publishes prebuilt `vociferate` binaries fo It also uploads `checksums.txt` for integrity verification. If a release already exists for the same tag, the workflow updates its release notes and replaces matching asset filenames so reruns stay in sync. - -## Reuse In Other Repositories - -Vociferate ships two composite actions that together cover the full release flow. -Pin both to the same released tag. - -### `prepare` — update files, commit, and push tag - -```yaml -name: Prepare Release - -on: - workflow_dispatch: - inputs: - version: - description: Optional semantic version override. - required: false - -jobs: - prepare: - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@v4 - with: - fetch-depth: 0 - - - uses: git.hrafn.xyz/aether/vociferate/prepare@v1.0.0 - with: - version: ${{ inputs.version }} - token: ${{ secrets.GITHUB_TOKEN }} -``` - -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. - -For repositories that embed the version inside source code, pass `version-file` -and `version-pattern`: - -```yaml -- uses: git.hrafn.xyz/aether/vociferate/prepare@v1.0.0 - with: - version-file: internal/myapp/version/version.go - version-pattern: 'const Version = "([^"]+)"' - git-add-files: changelog.md internal/myapp/version/version.go - token: ${{ secrets.GITHUB_TOKEN }} -``` - -### `publish` — create release with changelog notes - -```yaml -name: Do Release - -on: - push: - tags: - - "v*.*.*" - -jobs: - release: - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@v4 - - - uses: git.hrafn.xyz/aether/vociferate/publish@v1.0.0 - with: - token: ${{ secrets.GITHUB_TOKEN }} -``` - -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. - -The `publish` action outputs `release-id` so you can upload additional release -assets after it runs: - -```yaml -- id: publish - uses: git.hrafn.xyz/aether/vociferate/publish@v1.0.0 - with: - token: ${{ secrets.GITHUB_TOKEN }} - -- name: Upload my binary - run: | - curl --fail-with-body -X POST \ - -H "Authorization: token ${{ secrets.GITHUB_TOKEN }}" \ - -H "Content-Type: application/octet-stream" \ - "${{ github.api_url }}/repos/${{ github.repository }}/releases/${{ steps.publish.outputs.release-id }}/assets?name=myapp" \ - --data-binary "@dist/myapp" -```