From e30cc7f521bdefc704dc60725e9fb765d9b88675 Mon Sep 17 00:00:00 2001 From: Seth Wiesman Date: Wed, 20 May 2026 11:30:46 -0500 Subject: [PATCH 1/2] .agents/skills: add mz-dbt-release runbook Encodes the three-file release procedure for the dbt-materialize PyPI package: bump version in __version__.py + setup.py, date the Unreleased CHANGELOG entry, commit as `dbt-materialize: release vX.Y.Z` with a `Ship:` URL pointing at the feature/fix PR being released. Also notes which checks (cargo, bin/fmt, bin/lint) do not apply to a version-bump-only PR. --- .agents/skills/README.md | 1 + .agents/skills/mz-dbt-release/SKILL.md | 136 +++++++++++++++++++++++++ 2 files changed, 137 insertions(+) create mode 100644 .agents/skills/mz-dbt-release/SKILL.md diff --git a/.agents/skills/README.md b/.agents/skills/README.md index 85e52b9163bcd..988e7cb1f469e 100644 --- a/.agents/skills/README.md +++ b/.agents/skills/README.md @@ -19,6 +19,7 @@ explicitly with `$` in Codex and `/` in Claude Code. | **mz-commit** | Committing, creating PRs, pushing | Pre-commit checklist, PR title conventions, Cargo.lock discipline, git workflows | | **mz-pr-review** | Reviewing code changes | Local code review against Materialize standards for tests, style, error messages, architecture, and polish | | **mz-debug-ci** | CI failures, red builds, Buildkite issues | Investigates Buildkite failures using `gh` and `bk` CLI tools to identify root causes | +| **mz-dbt-release** | Cutting a new `dbt-materialize` PyPI release | Bumps the version in `__version__.py` + `setup.py`, dates the `Unreleased` CHANGELOG entry, opens the release PR | ## Performance diff --git a/.agents/skills/mz-dbt-release/SKILL.md b/.agents/skills/mz-dbt-release/SKILL.md new file mode 100644 index 0000000000000..74a3277a98cc9 --- /dev/null +++ b/.agents/skills/mz-dbt-release/SKILL.md @@ -0,0 +1,136 @@ +--- +name: mz-dbt-release +description: > + Trigger: "cut a dbt release", "release dbt-materialize", "release the dbt + adapter", "bump dbt-materialize version", "new dbt adapter version", or + opening the PR that ships an `Unreleased` CHANGELOG entry to PyPI. +--- + +# Cutting a dbt-materialize release + +A release PR bumps the published version of the `dbt-materialize` PyPI +package. It is mechanical: three files change, one commit, one PR. + +The adapter lives in `misc/dbt-materialize/`. PyPI publication is handled by +CI after the PR merges. + +## Files to touch + +Exactly three files: + +| File | Change | +|---|---| +| `misc/dbt-materialize/dbt/adapters/materialize/__version__.py` | Bump `version = "X.Y.Z"` | +| `misc/dbt-materialize/setup.py` | Bump `version="X.Y.Z"` (kwarg in `setup(...)`) | +| `misc/dbt-materialize/CHANGELOG.md` | Insert `## X.Y.Z - YYYY-MM-DD` between `## Unreleased` and the existing bullets | + +Both version strings must stay in sync — the comments in each file say so. + +## Picking the next version + +* Default: bump the **patch** component (`1.9.9 → 1.9.10`). +* The **minor** component tracks the required `dbt-postgres` minor. Only bump + minor when upgrading to a new `dbt-postgres` minor (e.g. `1.9.x → 1.10.0`). +* Read the current version from `__version__.py`. + +## Confirming what's being released + +The `## Unreleased` section of `CHANGELOG.md` is the source of truth for what +ships. If it's empty, there is nothing to release. Cross-check with: + +``` +git log ..HEAD -- misc/dbt-materialize/ +``` + +If a commit since the previous release touched `misc/dbt-materialize/` but is +not represented under `## Unreleased`, stop and ask whether it should be +included — don't silently invent a changelog entry. + +## CHANGELOG edit + +The release does **not** rewrite the unreleased bullets; it just dates them. +Insert a new dated heading immediately after `## Unreleased`, leaving +`## Unreleased` itself empty: + +``` +## Unreleased + +## 1.9.10 - 2026-05-20 + +* Support unmanaged clusters in `deploy_init`. ... +``` + +Use today's date in `YYYY-MM-DD`. + +## Branch, commit, PR + +* Branch name: `dbt-release-X.Y.Z` off `main` (or any commit that is an + ancestor of `upstream/main` — the `misc/dbt-materialize/` directory is the + only thing that matters). +* Commit subject: `dbt-materialize: release vX.Y.Z` +* Commit body / PR body: a single `Ship: ` line pointing at the PR that + triggered this release (the feature/fix PR being shipped). If multiple PRs + are being shipped, pick the headline one — the changelog already enumerates + them. +* PR title: same as the commit subject. +* PR targets `MaterializeInc/materialize:main`. + +Example: + +``` +gh pr create --repo MaterializeInc/materialize --base main \ + --head :dbt-release-1.9.10 \ + --title "dbt-materialize: release v1.9.10" \ + --body "Ship: https://github.com/MaterializeInc/materialize/pull/36625" +``` + +## What you do NOT run + +This PR touches only Python version strings and Markdown. Skip: + +* `cargo check`, `cargo clippy`, Cargo.lock work — no Rust changes. +* Test suites — there are no tests to add for a version bump. + +## Verifying before pushing + +``` +git diff --stat +``` + +Should show exactly three files with a `+4 / -2` shape (one line each in the +two version files, two added lines in `CHANGELOG.md`). If anything else is +staged, you've gone off-script. + +## Quick reference + +``` +# 1. Branch +git checkout -b dbt-release-X.Y.Z + +# 2. Edit the three files (see table above) + +# 3. Verify +git diff --stat # expect 3 files, +4/-2 + +# 4. Commit +git commit -am "dbt-materialize: release vX.Y.Z + +Ship: " + +# 5. Push and open PR +git push -u origin dbt-release-X.Y.Z +gh pr create --repo MaterializeInc/materialize --base main \ + --head :dbt-release-X.Y.Z \ + --title "dbt-materialize: release vX.Y.Z" \ + --body "Ship: " +``` + +## Historical reference + +Recent release commits (find via `git log --oneline -- misc/dbt-materialize/dbt/adapters/materialize/__version__.py`): + +* v1.9.10 — PR #36636 +* v1.9.9 — PR #36609 +* v1.9.8 — PR #36529 + +Inspect any of them with `git show ` to see the exact diff shape. From d1e2e560738bf7ced5557de2a46a09e62b4c5c48 Mon Sep 17 00:00:00 2001 From: Seth Wiesman Date: Wed, 20 May 2026 12:20:44 -0500 Subject: [PATCH 2/2] Apply suggestions from code review Co-authored-by: Jon Currey --- .agents/skills/mz-dbt-release/SKILL.md | 27 +++++++++++++++++--------- 1 file changed, 18 insertions(+), 9 deletions(-) diff --git a/.agents/skills/mz-dbt-release/SKILL.md b/.agents/skills/mz-dbt-release/SKILL.md index 74a3277a98cc9..7d9bfacebf90d 100644 --- a/.agents/skills/mz-dbt-release/SKILL.md +++ b/.agents/skills/mz-dbt-release/SKILL.md @@ -1,9 +1,14 @@ --- name: mz-dbt-release description: > - Trigger: "cut a dbt release", "release dbt-materialize", "release the dbt - adapter", "bump dbt-materialize version", "new dbt adapter version", or - opening the PR that ships an `Unreleased` CHANGELOG entry to PyPI. + Cut a dbt-materialize PyPI release: bump the version in `__version__.py` + and `setup.py`, date the `Unreleased` CHANGELOG entry, and open the + release PR with a `Ship: ` body. Trigger: "cut a dbt release", + "release dbt-materialize", "release the dbt adapter", "ship + dbt-materialize vX.Y.Z", "publish dbt-materialize to PyPI", "bump + dbt-materialize version", "new dbt adapter version". Use this skill + even if the user just says "ship the dbt adapter" or pastes a feature + PR and asks for "the next dbt release" without naming version mechanics. --- # Cutting a dbt-materialize release @@ -64,9 +69,7 @@ Use today's date in `YYYY-MM-DD`. ## Branch, commit, PR -* Branch name: `dbt-release-X.Y.Z` off `main` (or any commit that is an - ancestor of `upstream/main` — the `misc/dbt-materialize/` directory is the - only thing that matters). +* Branch name: `dbt-release-X.Y.Z`, branched from current `main`. * Commit subject: `dbt-materialize: release vX.Y.Z` * Commit body / PR body: a single `Ship: ` line pointing at the PR that triggered this release (the feature/fix PR being shipped). If multiple PRs @@ -91,15 +94,21 @@ This PR touches only Python version strings and Markdown. Skip: * `cargo check`, `cargo clippy`, Cargo.lock work — no Rust changes. * Test suites — there are no tests to add for a version bump. +`bin/fmt` and `bin/lint` cover `misc/dbt-materialize/*.py`, but a +one-character version bump almost never triggers them. Run them if +you've made an accidental wider change; otherwise they're optional. + ## Verifying before pushing ``` git diff --stat ``` -Should show exactly three files with a `+4 / -2` shape (one line each in the -two version files, two added lines in `CHANGELOG.md`). If anything else is -staged, you've gone off-script. +Should show exactly three files, predominantly a `+4 / -2` shape (one +line each in the two version files, two added lines in `CHANGELOG.md`). +A few extra lines in `CHANGELOG.md` are fine if a bullet was reformatted +while finalising it; an unexpected fourth file means you've gone +off-script. ## Quick reference