Pull Request

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:

1. Every PR needs exactly one semver label. Unlabeled PRs fail the PR Semver Labels CI check.
2. minor and major PRs require a blog post AND a roadmap update. The Check for changelog and roadmap updates workflow gates merging on both.
3. featured[] in the roadmap is curated. Never auto-promote a shipped milestone into featured[] — 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).

The label decision tree

The Atmos repo has four mutually exclusive release labels (plus other category labels that don't affect release docs):

How to choose

Ask, in order:

1. Would a user upgrading Atmos see ANY visible change? 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.
2. 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.
3. Is this net-new functionality? New command, new flag, new config option that users will adopt? Use minor. Write a blog post.
4. 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.

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:

1. 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 key

   If commit.gpgsign is not true, set it for the repo:

   git config commit.gpgsign true

2. After your first commit, verify it's signed:

   git log --show-signature -1

   Look for gpg: Good signature from ... or Good "git" signature for .... If you see "no signature found", stop and fix your git config before pushing.

3. Never bypass signing with --no-gpg-sign or -c commit.gpgsign=false even temporarily. The CLAUDE.md rules forbid this, and the resulting commit cannot be merged.

If you discover unsigned commits already on the branch:

# For the last N commits (interactive rebase, sign each):
git rebase --exec 'git commit --amend --no-edit -S' -i HEAD~N
git push --force-with-lease

Always use --force-with-lease (not --force) to avoid clobbering work from other sessions on the same branch.

Pre-push checklist

Run through these in order before git push. Every item has burned someone before.

1. Identify the smallest accurate label. Use the decision tree above. Default to no-release for plumbing.
2. Confirm commit signing is on (see above). One unsigned commit blocks the entire PR from merging.
3. If minor or major:
   • Create a blog post at website/blog/YYYY-MM-DD-<slug>.mdx.
   • Read website/blog/tags.yml and pick a defined tag.
   • Check website/blog/authors.yml for 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 roadmap skill (do not touch featured[]).
4. Build the website to verify MDX renders: cd website && npm run build.
5. Commit and push.