From 0db09fa36dd40cb0410411c5f6ab2814aa4c2cb9 Mon Sep 17 00:00:00 2001 From: Catherine Fritz <111930712+fivetran-catfritz@users.noreply.github.com> Date: Wed, 7 Oct 2026 17:34:46 -0500 Subject: [PATCH 1/3] Scaffold a .changes/*.yml template automatically when a PR is opened Adds a new scaffold-changes-template job to check-docs-current.yml, gated on github.event.action == 'opened' so it fires exactly once per PR (not on every push). It checks out the PR's actual head branch (not the default merge ref), skips if a real .changes/*.yml or the template already exists, downloads templates/changes-template.yml, and commits it as .changes/TODO.yml.template - a deliberately inert extension that release_yaml_files()'s *.yml glob never matches, so it can't be mistaken for a real release entry until renamed. Reuses the existing check-docs-current.yml caller already deployed in every package repo (on: pull_request: types: [opened, synchronize, reopened]) - no new per-repo workflow file needed. Skipped entirely for fork PRs, since GITHUB_TOKEN/secrets.GH_TOKEN can't push there. Verified: the skip-if-exists check (ls-based, not compgen -G - that doesn't reliably signal "no match" via exit status) against all three cases (nothing exists, real entry exists, template exists), and that templates/changes-template.yml is fetchable from the POC branch URL this hardcodes for now. Co-Authored-By: Claude Sonnet 5 --- .github/workflows/check-docs-current.yml | 56 ++++++++++++++++++++++++ README.md | 6 ++- 2 files changed, 60 insertions(+), 2 deletions(-) diff --git a/.github/workflows/check-docs-current.yml b/.github/workflows/check-docs-current.yml index 78a2e50..95bc135 100644 --- a/.github/workflows/check-docs-current.yml +++ b/.github/workflows/check-docs-current.yml @@ -3,8 +3,64 @@ name: Check docs current on: workflow_call: +permissions: + contents: write + jobs: + scaffold-changes-template: + # Runs once, when the PR is first opened, to drop a copy-paste-ready + # .changes/*.yml template into the branch. Skipped for fork PRs, since + # GITHUB_TOKEN/secrets.GH_TOKEN can't push to a fork's branch. + if: >- + github.event.action == 'opened' && + github.event.pull_request.head.repo.full_name == github.repository + runs-on: ubuntu-latest + steps: + - name: Checkout repo + uses: actions/checkout@v4 + with: + fetch-depth: 0 + token: ${{ secrets.GH_TOKEN }} + + - name: Checkout PR branch + run: | + git checkout -B "$BRANCH_NAME" "origin/$BRANCH_NAME" + git pull --rebase origin "$BRANCH_NAME" + env: + BRANCH_NAME: ${{ github.event.pull_request.head.ref }} + + - name: Skip if a changes entry or template already exists + id: existing + run: | + if ls .changes/*.yml >/dev/null 2>&1 || [ -f ".changes/TODO.yml.template" ]; then + echo "skip=true" >> "$GITHUB_OUTPUT" + else + echo "skip=false" >> "$GITHUB_OUTPUT" + fi + + - name: Download changes-template.yml + if: steps.existing.outputs.skip == 'false' + # Hardcoded to the changelog POC test branch for now (see GA-1035597). + # Update this ref once that work lands on main. + run: | + mkdir -p .changes + curl -sSfL \ + "https://raw.githubusercontent.com/fivetran/dbt_package_automations/refs/heads/changelog-poc/initial-test/templates/changes-template.yml" \ + -o .changes/TODO.yml.template + + - name: Commit and push the template + if: steps.existing.outputs.skip == 'false' + run: | + git config --global user.name "fivetran-data-model-bot" + git config --global user.email "fivetran-data-model-bot@users.noreply.github.com" + git add .changes/TODO.yml.template + git commit -m "Add .changes/*.yml template" || echo "No changes to commit" + git push origin "$BRANCH_NAME" + env: + BRANCH_NAME: ${{ github.event.pull_request.head.ref }} + check-docs: + if: github.event.action != 'opened' runs-on: ubuntu-latest steps: - name: Checkout diff --git a/README.md b/README.md index 5f4caa2..b58e285 100644 --- a/README.md +++ b/README.md @@ -8,7 +8,7 @@ This repository includes: - **GitHub Actions workflows** (`/.github/workflows/`) - `auto-release.yml` – Automates GitHub release creation - - `check-docs-current.yml` – Checks three things on every PR push: docs regenerated, `CHANGELOG.md` updated, and a `.changes/*.yml` entry present. Reports a single `docs/generated` commit status naming specifically which of the three are missing, and removes the `docs:ready` label if any are stale + - `check-docs-current.yml` – When a PR is opened, drops a `.changes/TODO.yml.template` into the branch if no `.changes/*.yml` entry exists yet (skipped for fork PRs). On every subsequent push, checks three things: docs regenerated, `CHANGELOG.md` updated, and a `.changes/*.yml` entry present. Reports a single `docs/generated` commit status naming specifically which of the three are missing, and removes the `docs:ready` label if any are stale - `generate-docs.yml` – When the `docs:ready` label is applied, generates dbt documentation **and** runs the changelog update (see below) in one job, committing both to the PR branch in a single push. Reports a `docs/generated` failure status and removes the `docs:ready` label if either step fails ## Changelog generation @@ -94,4 +94,6 @@ contributors: Only `version` is required — omit any section with nothing to report for this release. A blank, copy-paste-ready starting point lives at -[`templates/changes-template.yml`](templates/changes-template.yml). \ No newline at end of file +[`templates/changes-template.yml`](templates/changes-template.yml), and `check-docs-current.yml` +automatically drops a copy into new PRs as `.changes/TODO.yml.template` (the `.yml.template` +extension is deliberate — it's never picked up as a release until renamed to `.changes/{version}.yml`). \ No newline at end of file From f19ffa47790874043400a6edad9a85bd5747f622 Mon Sep 17 00:00:00 2001 From: Catherine Fritz <111930712+fivetran-catfritz@users.noreply.github.com> Date: Wed, 7 Oct 2026 17:44:40 -0500 Subject: [PATCH 2/3] Trim the fork-skip comment to state, not explain Co-Authored-By: Claude Sonnet 5 --- .github/workflows/check-docs-current.yml | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/.github/workflows/check-docs-current.yml b/.github/workflows/check-docs-current.yml index 95bc135..126dc0b 100644 --- a/.github/workflows/check-docs-current.yml +++ b/.github/workflows/check-docs-current.yml @@ -9,8 +9,7 @@ permissions: jobs: scaffold-changes-template: # Runs once, when the PR is first opened, to drop a copy-paste-ready - # .changes/*.yml template into the branch. Skipped for fork PRs, since - # GITHUB_TOKEN/secrets.GH_TOKEN can't push to a fork's branch. + # .changes/*.yml template into the branch. Skipped for fork PRs. if: >- github.event.action == 'opened' && github.event.pull_request.head.repo.full_name == github.repository From 55e96d4a6a5e0be7058ff64cf318237e8fe31863 Mon Sep 17 00:00:00 2001 From: Catherine Fritz <111930712+fivetran-catfritz@users.noreply.github.com> Date: Wed, 7 Oct 2026 17:58:44 -0500 Subject: [PATCH 3/3] Fix: scaffolding the template made check-docs-current.yml think .changes was current RELEVANT_CHANGES_YML checked the whole .changes/ path, so the scaffold job's own commit (adding .changes/TODO.yml.template) counted as "last touched .changes/" - making the three-way check think a real changelog entry existed when only the inert template did. Scoped the pathspec to .changes/*.yml specifically, which the template's .yml.template extension doesn't match. Reproduced against a live test PR (fivetran/dbt_amazon_ads#55): after the scaffold job added the template, the docs/generated status wrongly read "Missing: docs regeneration, CHANGELOG.md update" - note the absence of "a .changes/*.yml entry", which should have still been there. Verified locally that scoping the pathspec to .changes/*.yml fixes it. Co-Authored-By: Claude Sonnet 5 --- .github/workflows/check-docs-current.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/check-docs-current.yml b/.github/workflows/check-docs-current.yml index 126dc0b..1d15fe6 100644 --- a/.github/workflows/check-docs-current.yml +++ b/.github/workflows/check-docs-current.yml @@ -97,7 +97,7 @@ jobs: RELEVANT_DOCS=$(relevant_since_last_touch 'docs/') RELEVANT_CHANGELOG=$(relevant_since_last_touch 'CHANGELOG.md') - RELEVANT_CHANGES_YML=$(relevant_since_last_touch '.changes/') + RELEVANT_CHANGES_YML=$(relevant_since_last_touch '.changes/*.yml') echo "BASE: $BASE" echo "HEAD: $HEAD"