Pull Request Preparation (Atmos)
Use this skill every time you open or update a PR. It encodes three policies that the Atmos repo enforces via CI and that the team has been burned by repeatedly:
- Every PR needs exactly one semver label. Unlabeled PRs fail the
PR Semver LabelsCI check. minorandmajorPRs require a blog post AND a roadmap update. TheCheck for changelog and roadmap updatesworkflow gates merging on both.featured[]in the roadmap is curated. Never auto-promote a shipped milestone intofeatured[]— only the user decides.
If you violate any of these, CI fails and the PR can't merge. Follow this skill across both phases: complete the pre-push checklist before git push, then immediately work through the post-push / PR checklist (open the PR, apply the label, monitor CI).
Stacked PRs
Before creating or updating dependent PRs, read the gh-stack skill.
Discover the gh stack extension and inspect native membership before choosing propagation.
When native registration is requested or otherwise authorized, use gh stack link or the appropriate
submission workflow and verify GitHub's membership and order. Setting --base alone creates only
a branch chain; preserve an ordinary chain's classification unless conversion is authorized.
Stay below the 150-file review boundary against each PR's actual parent; the repository quality
gate currently permits at most 149 files. Native stacks require linear history between branches;
batch fixes before a necessary cascading rebase instead of merging parents as a general workaround
or rebasing after every finding. Verify the current direct-parent chain before requesting reviews.
GitHub can retain approvals for unchanged PR diffs, but do not promise retention; report affected
approvals at risk before publication. Verify reviews separately from CI. For non-bot PRs, Atmos's
Quality Gate requires exact-head CodeRabbit approval (bot-authored PRs are exempt); inspect the live review commit ID before requesting another
review, because GitHub may associate a retained approval with the new head.
Coordinate history repair and publication through that skill.
For an explicitly independent PR, target trunk and leave it outside the existing stack.
The label decision tree
The Atmos repo has four mutually exclusive release labels (plus other category labels that don't affect release docs):
| Label | When | CI requires blog + roadmap? |
|---|---|---|
no-release |
Internal refactor, CI/release tooling, distribution-only changes, dependency bumps without application changes, docs fixes | No |
patch |
Bug fix, performance fix, error-message improvement, small UX polish — user-visible but not a feature | No |
minor |
New user-visible feature, new flag, new command, new config option, default flip that users see | YES |
major |
Breaking change: removed/renamed flag, schema migration, CLI behavior reversal | YES |
How to choose
Classify the public application contract, not file extensions, dependency
version numbers, or the presence of an announcement. CI, runner pinning, cache
changes, release tooling (including Go code in Mage), and prebuilt distribution
changes use no-release when they do not change Atmos's application behavior.
Retiring prebuilt binaries or packages while retaining installation from source
is a distribution-policy change; it does not by itself require Atmos 2.0.
Communicate the affected platforms and installation alternatives in a changelog
when requested, without inferring a major label from that announcement.
Before applying major, identify the exact incompatible CLI/API/configuration
contract and the migration it requires. A changed download matrix, a dependency's
major version, a changelog tag, or the fact that users must change their installation
method is insufficient on its own. If application compatibility is unchanged,
use no-release; if the PR also changes application behavior, classify that
behavior using the decision tree below. Never create or demand a major milestone
solely for build or distribution changes.
Ask, in order:
- Would a user upgrading Atmos see a change in the application's behavior? Output, errors, performance, new flags, new commands, removed flags, changed defaults? If no, use
no-release. This is the most common case for foundation/plumbing PRs; distribution availability is handled separately above. - Is this a breaking change? Removed flags, renamed flags, changed semantics, schema bumps that require user action? Use
major. Document the migration in the blog post. - Is this net-new functionality? New command, new flag, new config option that users will adopt? Use
minor. Write a blog post. - Anything else user-visible (bug fix, UX polish, error-message rewrite, output formatting): use
patch. No blog post required.
Common mistake: labeling a plumbing PR as minor because it's part of a larger feature. The label is per-PR, not per-feature. If a five-PR stack adds one user-visible feature, only the final PR that wires it up gets minor — the four foundation PRs are no-release.
Another common mistake: flipping a default value and labeling patch because "it's just a default." If users see different behavior on upgrade, that's minor (or major if it could break their workflow).
Apply the label as the first action
After opening the PR, immediately:
gh pr edit <pr-number> --add-label <label>
Don't wait for CI to complain — you already know the label.
If you're opening multiple related PRs that are foundation work, label them all no-release up front:
for pr in 2417 2418 2419; do gh pr edit "$pr" --add-label no-release; done
Changing a label later requires removing the old one first. --add-label doesn't replace — running --add-label minor on a PR already labeled patch leaves both attached, which violates the "exactly one semver label" invariant and fails the PR Semver Labels CI gate:
# Wrong — leaves both labels:
gh pr edit <pr-number> --add-label minor
# Right — remove the old semver label first, then add the new one:
gh pr edit <pr-number> --remove-label patch --add-label minor
gh pr edit accepts --remove-label and --add-label in the same invocation, so the relabel is atomic.
Release milestone — choose it when opening the PR
Every PR except no-release must have a stable versioned milestone. Labels state
minimum compatibility; the milestone's version is the release authority.
Read current milestones and the highest published stable release. Use the tested
policy in magefiles/release/milestone/ to choose the lowest open milestone that
can accommodate the PR's label (patch fits patch/minor/major, minor fits
minor/major, major fits major). Assign it with gh pr edit --milestone <title>.
Never infer a new version from labels or automatically create patch/major slots.
If no suitable milestone exists, report that a maintainer must create one.
Only PRs in the lowest open release milestone may merge. A PR assigned to a
later compatible milestone is planned correctly but remains blocked until earlier
milestones close. no-release bypasses milestone assignment and ordering.
Preserve an existing manually assigned milestone; do not silently move it to make
CI green. Explain an incompatible label/milestone and let the maintainer resolve
intent. atmos release milestones check reconciles the current merge statuses.
See releases for the operator release process.
Blog post (changelog) — when, where, and who owns it
Required only when the PR is labeled minor or major. CI checks for a new .mdx file under website/blog/. If you have the wrong label, fix the label rather than writing a blog post you don't need.
For the template, tags, authors, and style rules, use the changelog skill — don't re-derive them here.
For what does NOT get a post (internal-only, zero-user-impact refactors), the roadmap skill owns that
invariant. Default to "no blog post" when in doubt and let the label decision tree above settle it.
Roadmap — when required, who owns it
Required only when the PR is labeled minor or major. CI checks for changes to website/src/data/roadmap.js.
Always delegate the edit to the roadmap skill (.claude/skills/roadmap/SKILL.md) — invoke via Skill with skill: "roadmap". It owns the milestone schema, the featured[]-is-curated rule, the no-changelog-for-internal-refactors invariant, and progress-percentage math. Do not edit roadmap.js directly from this skill; invoke the roadmap skill and let it do the work.
If your PR is no-release or patch, don't touch the roadmap at all — CI doesn't require it for those labels, and adding noise milestones dilutes the roadmap's signal value.
Signed commits (MANDATORY — branch protection blocks merge)
Every commit on the PR must be GPG- or SSH-signed. Branch protection on main rejects merges of any PR containing unsigned commits — there is no override. If you push unsigned commits, you will rewrite history later to re-sign them, which is painful for reviewers (force-push invalidates their in-progress reviews).
Get this right the first time:
Verify your local git is configured to sign automatically before your first commit:
git config --get commit.gpgsign # should print: true git config --get gpg.format # "openpgp" or "ssh" git config --get user.signingkey # your signing keyIf
commit.gpgsignis nottrue, set it for the repo:git config commit.gpgsign trueAfter your first commit, verify it's signed:
git log --show-signature -1Look for
gpg: Good signature from ...orGood "git" signature for .... If you see "no signature found", stop and fix your git config before pushing.Never bypass signing with
--no-gpg-signor-c commit.gpgsign=falseeven temporarily. The CLAUDE.md rules forbid this, and the resulting commit cannot be merged.
Repair unsigned commits before publishing. If they are already published, inspect the affected branches and reviews, verify the required repair, and confirm that existing authorization covers rewriting that history. For stacked PRs, coordinate through the gh-stack skill; do not automatically rebase every descendant. If a permitted history rewrite is necessary, use an explicit expected-SHA lease to protect against concurrent remote work, never an unconditional force push. A lease does not itself authorize the rewrite, and restricted invocations may prohibit it.
Normal updates use ordinary fast-forward pushes. A rejected push requires inspecting remote changes, not automatically escalating to a force-push flag.
Pre-push checklist
Run through these in order before git push. Every item has burned someone before.
- Identify the smallest accurate label. Use the decision tree above. Default to
no-releasefor plumbing. - Confirm commit signing is on (see above). One unsigned commit blocks the entire PR from merging.
- If
minorormajor:- Create a blog post at
website/blog/YYYY-MM-DD-<slug>.mdx. - Read
website/blog/tags.ymland pick a defined tag. - Check
website/blog/authors.ymlfor your handle; add yourself if missing. - Embed the feature's cast (
CastEmbed) if one exists or was recorded for this PR. - Delegate the roadmap update to the
roadmapskill (do not touchfeatured[]).
- Create a blog post at
- Build the website to verify MDX renders:
cd website && npm run build. - Commit and push.
Post-push / PR checklist
Once the branch is on GitHub, finish the workflow:
- Open the PR with title (under 70 chars) + body using the project's PR template (what / why / references). See the gotcha below about
gh pr createbody formatting. - Apply the label immediately after opening:
gh pr edit <num> --add-label <label>. - If the PR fixes a tracked issue: include
Closes #<issue>in the PR body so it auto-closes on merge. - Check CI status after the first push:
gh pr checks <num>. IfPR Semver Labels,Check for changelog and roadmap updates, or signed-commit verification fails, fix it before requesting review. - Address CodeRabbit comments as they arrive. For substantial review threads (5+ comments, or any comment spanning multiple files), delegate to the
coderabbit-reviewagent viaAgentwithsubagent_type: "coderabbit-review"— it knows how to parse CR threads, verify each finding against current code, and skip stale or wrong ones with explanation instead of silently ignoring them.
Gotcha: gh pr create --body and backtick escaping
Do NOT escape backticks (\`) inside a single-quoted heredoc passed to gh pr create --body. The single-quoted form preserves the backslashes literally, so GitHub renders them as escaped characters instead of rendering the code spans. The result is a PR body full of \atmos.yaml`instead ofatmos.yaml`.
Wrong (produces visible ``` in the PR body):
gh pr create --body "$(cat <<'EOF'
This file is named \`atmos.yaml\`.
EOF
)"
Right — write a .md file and pass it with --body-file:
cat > /tmp/pr-body.md <<'EOF'
This file is named `atmos.yaml`.
EOF
gh pr create --body-file /tmp/pr-body.md
(Alternatively, the single-quoted heredoc already disables shell expansion, so plain unescaped backticks work — but --body-file is more robust because file content survives shell quoting unchanged.)
Updating an existing PR
If a PR has already been opened without a label, or with the wrong one:
Run
gh pr view <num> --json labelsto see what's already attached. Look for any ofno-release/patch/minor/major— at most one should remain.Apply the decision tree to pick the correct label.
If the PR has no semver label yet: add it.
gh pr edit <num> --add-label <label>If the PR has a different semver label already: remove the old one and add the new one in a single invocation, so you never have two semver labels at once (which fails CI):
gh pr edit <num> --remove-label <old-label> --add-label <new-label>If you changed from
no-release/patchtominor/major, you now owe a blog post and roadmap update — add them in a new commit on the same branch.If you changed from
minor/majorto a lower label, you can (optionally) remove the blog post and roadmap update in a new commit, but it's also fine to leave them.
Related skills and agents
This skill orchestrates the PR workflow but delegates the deep domain work to dedicated skills and agents. Use them — don't re-derive their rules here.
changelogskill — invoke when writing or editing awebsite/blog/*.mdxpost. Owns the template, tags, authors, and style rules. Invoke viaSkillwithskill: "changelog".roadmapskill — invoke when you need to editwebsite/src/data/roadmap.js. Owns the milestone schema,featured[]curation rule, no-changelog-for-internal-refactors invariant, and progress-percentage math. Invoke viaSkillwithskill: "roadmap".editionsskill — invoke when a PR changes what a config key defaults to, or changes what an existing stored value effectively means (even via a brand-new key). Decides whetherpkg/edition/journal.goneeds aKindValueentry, whether a new automatic-behavior default should preserve prior behavior instead, and when to add aKindBehaviorRoadmap candidate note indocs/prd/editions.mdfor a reinterpretation the journal can't gate yet. Invoke viaSkillwithskill: "editions".coderabbit-reviewagent — invoke when a CodeRabbit review lands with substantial feedback. Knows how to parse CR threads, verify findings against current code, apply valid suggestions, and skip stale/wrong ones with explanation. Invoke viaAgentwithsubagent_type: "coderabbit-review".
If your PR also touches a specific Atmos subsystem, the matching domain agent is the right collaborator for the implementation work (separate from this PR-workflow skill):
agent-developer— creating or updating agentsatmos-errors— error handling codeflag-handler— CLI flag wiringtui-expert— terminal UI / theme systemtui-list— list commandsexample-creator— examples underexamples/gist-creator— gist documentation
Reference
- CI workflow:
.github/workflows/changelog-check.yml(release docs gate) - CI workflow:
.github/workflows/feature-release.yml(semver label gate) - Blog post authoring:
changelogskill (.claude/skills/changelog/SKILL.md) - Roadmap data and editing rules:
roadmapskill (.claude/skills/roadmap/SKILL.md) - Project rules:
CLAUDE.md(search for "Pull Requests", "Blog Posts", "Roadmap Updates")
