From 527521279af16b3657c6056ca823cb9ac767bc70 Mon Sep 17 00:00:00 2001 From: Marcus Date: Mon, 13 Jul 2026 07:46:08 +0100 Subject: [PATCH] Update Changelog on new tag --- .github/workflows/config-reference.yaml | 63 +++++++++++++++++++------ CONTRIBUTING.md | 24 ++++++---- 2 files changed, 62 insertions(+), 25 deletions(-) diff --git a/.github/workflows/config-reference.yaml b/.github/workflows/config-reference.yaml index bc8516e62..72c6d04f1 100644 --- a/.github/workflows/config-reference.yaml +++ b/.github/workflows/config-reference.yaml @@ -1,8 +1,8 @@ --- # Automates step 8 of the release process in CONTRIBUTING.md: when a release -# tag is pushed, regenerate the versioned NativeLink configuration reference -# (web/apps/docs) from that tag and open a PR against main with auto-merge -# enabled. +# tag is pushed, regenerate the canonical changelog plus the versioned +# NativeLink configuration reference (web/apps/docs) from that tag and open a PR +# against main with auto-merge enabled. # # The generator needs the tag to exist (it builds the config schema from a # `git worktree` of the tag), which is why this runs on tag push rather than @@ -13,9 +13,9 @@ # - A `WORKFLOW_PR_TOKEN` secret (fine-grained PAT or GitHub App token with # contents:write + pull-requests:write). PRs created with the default # GITHUB_TOKEN do not trigger CI workflows, so required checks would never -# report and auto-merge would never fire. Without the secret this workflow -# still opens the PR; it just needs a human to merge it. -name: Regenerate config reference +# report and auto-merge would never fire. Some repositories also block the +# default GITHUB_TOKEN from creating pull requests at all. +name: Regenerate release docs on: push: @@ -26,7 +26,7 @@ on: workflow_dispatch: inputs: tag: - description: 'Existing release tag to regenerate the config reference for (e.g. v1.6.1).' + description: 'Existing release tag to regenerate release docs for (e.g. v1.6.1).' required: true type: string @@ -61,6 +61,25 @@ jobs: fi echo "tag=${TAG}" >> "${GITHUB_OUTPUT}" + - name: Validate PR token + env: + WORKFLOW_PR_TOKEN: ${{ secrets.WORKFLOW_PR_TOKEN }} + run: | + set -euo pipefail + if [[ -n "${WORKFLOW_PR_TOKEN}" ]]; then + exit 0 + fi + + cat >> "${GITHUB_STEP_SUMMARY}" <<'EOF' + ## Missing WORKFLOW_PR_TOKEN + + This workflow must push the generated branch and open a pull request + with a token that can trigger normal CI. Add a repository secret named + `WORKFLOW_PR_TOKEN` with `contents:write` and `pull-requests:write`. + EOF + echo "::error::WORKFLOW_PR_TOKEN is required; the default GITHUB_TOKEN cannot reliably create CI-triggering pull requests." + exit 1 + - name: Checkout uses: >- # v6.0.2 actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd @@ -69,6 +88,7 @@ jobs: # release tag itself, so it needs the full history and all tags. ref: main fetch-depth: 0 + token: ${{ secrets.WORKFLOW_PR_TOKEN }} - name: Prepare Worker uses: ./.github/actions/prepare-nix @@ -82,23 +102,36 @@ jobs: bun install && bun --filter @nativelink/docs gen:config-reference ${{ steps.resolve.outputs.tag }} " + - name: Regenerate changelog + env: + TAG: ${{ steps.resolve.outputs.tag }} + run: | + nix develop --impure --command bash -c ' + set -euo pipefail + # End the range at the release tag so post-tag commits on main do + # not become a duplicate section for the same version. + ROOT_COMMIT=$(git rev-list --max-parents=0 "${TAG}" | tail -1) + git cliff --tag "${TAG}" --output CHANGELOG.md "${ROOT_COMMIT}..${TAG}" + ' + - name: Lint generated docs run: | nix develop --impure --command bash -c " + vale CHANGELOG.md vale web/apps/docs/content/docs/reference/nativelink-config/*.mdx " - name: Open auto-merge PR env: - GH_TOKEN: ${{ secrets.WORKFLOW_PR_TOKEN || github.token }} + GH_TOKEN: ${{ secrets.WORKFLOW_PR_TOKEN }} TAG: ${{ steps.resolve.outputs.tag }} run: | set -euo pipefail # The generator also creates new untracked pages (the previous # latest release gets its own versioned page), so check the whole # docs tree, not just tracked modifications. - if [[ -z "$(git status --porcelain -- web/apps/docs)" ]]; then - echo "Config reference already up to date for ${TAG}; nothing to do." + if [[ -z "$(git status --porcelain -- CHANGELOG.md web/apps/docs)" ]]; then + echo "Release docs already up to date for ${TAG}; nothing to do." exit 0 fi @@ -106,17 +139,17 @@ jobs: git config user.name "github-actions[bot]" git config user.email "41898282+github-actions[bot]@users.noreply.github.com" git switch -c "${BRANCH}" - git add web/apps/docs - git commit -m "docs(config-reference): regenerate for NativeLink ${TAG}" - git push --force origin "${BRANCH}" + git add CHANGELOG.md web/apps/docs + git commit -m "docs(release): regenerate for NativeLink ${TAG}" + git push --force-with-lease origin "HEAD:${BRANCH}" PR_URL=$(gh pr list --head "${BRANCH}" --base main --state open --json url --jq '.[0].url // empty') if [[ -z "${PR_URL}" ]]; then PR_URL=$(gh pr create \ --base main \ --head "${BRANCH}" \ - --title "docs(config-reference): regenerate for NativeLink ${TAG}" \ - --body "Automated regeneration of the NativeLink configuration reference for ${TAG} (CONTRIBUTING.md release step 8). Generated by the \`${{ github.workflow }}\` workflow.") + --title "docs(release): regenerate for NativeLink ${TAG}" \ + --body "Automated regeneration of the NativeLink changelog and configuration reference for ${TAG} (CONTRIBUTING.md release step 8). Generated by the \`${{ github.workflow }}\` workflow.") fi echo "PR: ${PR_URL}" diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 8d05b1701..43d281b66 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -399,7 +399,7 @@ most automatically generated changelogs provide. - `Cargo.toml` - `nativelink-*/Cargo.toml` -2. Run `git cliff --tag=0.x.y > CHANGELOG.md` to update the changelog. You might +2. Run `git cliff --tag=v0.x.y > CHANGELOG.md` to update the changelog. You might need to make manual adjustments to `cliff.toml` if `git-cliff` doesn't put a commit in the right subsection. @@ -437,15 +437,17 @@ most automatically generated changelogs provide. git push upstream v0.x.y ``` -8. Regenerate the latest config reference docs now that the upstream tag exists. +8. Regenerate the release docs now that the upstream tag exists. Pushing the tag upstream triggers the - [`Regenerate config reference`](.github/workflows/config-reference.yaml) - workflow, which regenerates the docs and opens a PR against `main` with - auto-merge enabled. Check that the PR appeared and merged; if the workflow - failed, either re-run it from `Actions → Regenerate config reference → Run - workflow` (entering the tag) or fall back to the manual procedure below. - - Passing the new tag updates `web/apps/docs/lib/config-versions.ts`, which + [`Regenerate release docs`](.github/workflows/config-reference.yaml) + workflow, which regenerates `CHANGELOG.md` plus the config reference docs and + opens a PR against `main` with auto-merge enabled. Check that the PR appeared + and merged; if the workflow failed, either re-run it from `Actions → + Regenerate release docs → Run workflow` (entering the tag) or fall back to the + manual procedure below. + + Passing the new tag updates `CHANGELOG.md` from the exact commit range ending + at the tag. It also updates `web/apps/docs/lib/config-versions.ts`, which determines the latest version shown in the docs UI, rewrites `web/apps/docs/content/docs/reference/nativelink-config/index.mdx` from that tag, and creates a versioned page for the previous latest release. You do not @@ -453,6 +455,8 @@ most automatically generated changelogs provide. ```bash git fetch --tags upstream + ROOT_COMMIT=$(git rev-list --max-parents=0 v0.x.y | tail -1) + git cliff --tag v0.x.y --output CHANGELOG.md "${ROOT_COMMIT}..v0.x.y" cd web bun --filter @nativelink/docs gen:config-reference v0.x.y cd .. @@ -465,7 +469,7 @@ most automatically generated changelogs provide. the generated docs update: ```bash - nix develop -c vale web/apps/docs/content/docs/reference/nativelink-config/*.mdx + nix develop -c vale CHANGELOG.md web/apps/docs/content/docs/reference/nativelink-config/*.mdx ``` 9. The images for the release are now being created. Go to the