contributing: one step per PR, a required gate, SDK release train

[foxnne]

Builds on #229, now merged. sdk-tag.yml no longer repacks a released SDK tarball, which the release train below depends on. Its first live run, on #229's own merge, published nothing, as intended.

What changes

This writes down how a change gets to main, in the repo, where every session and contributor reads it. Until now these rules lived in one person's local agent memory, where a cloud session (or a second person) never saw them. CLAUDE.md had also drifted: it still called the SDK "0.2.0, unreleased".

CONTRIBUTING.md, imported by CLAUDE.md (@CONTRIBUTING.md):

• One plan step, one branch, one PR.
  • Plans are issues; a plan is never the PR its implementation lands in.
  • Aim for about 800 lines or fewer of non-test, non-doc diff; bigger work goes in a stack or behind a flag.
  • Branches are named <area>/<slug> and never reused.
  • The PR title is the squash commit: area: what changes, at most 72 characters.
• Claim before you build. Check gh pr list for overlap, then open a draft PR on the first push. Drafts don't take the web test copy. The open PR list is the who's-on-what board for laptop sessions, cloud sessions and people alike.
• jj.
  • No git write commands.
  • Work in a workspace of your own (the default checkout is shared).
  • jj new before the work, not after.
  • Backticks go through --stdin / --body-file.
  • Push a branch, never main.
  • After a merge, forget the PR's workspace, then jj git fetch, which drops the merged changes (seen on ci: sdk-tag never replaces a released SDK tarball #229).
• Verify, and say how.
  • The five gates (CI doesn't run test-integration).
  • Read the Build Summary rather than the test count.
  • A plugin build installs into the real plugins dir.
  • UI changes say how they were seen, and on which platforms.
• The SDK on a release train.
  • A feature PR records recorded_sdk_shape_fingerprint, leaves sdk_version alone, and is labelled sdk.
  • Only an sdk: release 0.2.N PR bumps the version. Two branches never race for the same number, and a morning's SDK changes cost one repin round instead of several (0.2.3 → 0.2.17 was 15 releases in 12 days).
  • Release soon after a fingerprint move, because fizzyed.it/app runs main.
  • An app release never ships an unreleased fingerprint.

Kept consistent with it: the doc comments in sdk/src/version.zig, sdk/sdk_version.zig and sdk/src/dylib.zig, docs/PLUGINS.md § Compatibility, and RELEASING.md (VERSION is bumped through a PR, with the SDK released first if the fingerprint moved). In CLAUDE.md, the Build block now lists test-integration and notes that CI doesn't run it. The LIB_CHECKPOINT.md link now says its ground rules are superseded where they differ.

CI (ci.yml):

• ci-ok is one job that passes when every other job passed or was skipped, and fails on any failure or cancellation. It is the single check the ruleset requires.
• The workflow-level paths-ignore is gone. It would never start CI for a Markdown-only PR, leaving that PR's required check waiting forever. A changes job decides instead whether the builds run.
• merge_group: is added, so turning on a merge queue later needs no workflow change.

.github/rulesets/main.json is the reviewable record of main's ruleset: squash-only PRs, ci-ok required, no force-push or deletion. Org admins may merge a PR past a failing check (bypass_mode: pull_request) but can't push to main directly.

.github/pull_request_template.md has sections for what changes, SDK impact, per-platform verification, and follow-ups.

After merging: repo settings (yours to apply)

# 1. The ruleset (after this PR's ci-ok has run once, so the check exists)
gh api -X POST repos/fizzyedit/fizzy/rulesets --input .github/rulesets/main.json

# 2. Squash commits take the PR title and body; rebase merges off
gh api -X PATCH repos/fizzyedit/fizzy -f squash_merge_commit_title=PR_TITLE -f squash_merge_commit_message=PR_BODY -F allow_rebase_merge=false

# 3. The label the release train uses
gh label create sdk --repo fizzyedit/fizzy --color 5319e7 --description "Moves the plugin boundary's fingerprint; ships at the next SDK release"

# 4. Optional, once the ruleset is active: retire the classic branch protection so one place says what main requires
gh api -X DELETE repos/fizzyedit/fizzy/branches/main/protection

Behaviour changes to expect:

• Direct pushes to main are refused, including the old RELEASING.md flow, which this PR changes.
• The Markdown-only skip now happens inside the workflow, so Changes and ci-ok run (a few seconds each) on every PR.

SDK impact

• None. Doc comments only under sdk/; no fingerprint or version change. With ci: sdk-tag never replaces a released SDK tarball #229 merged, the sdk-tag.yml run this merge triggers publishes nothing.

#228 bumps sdk_version in a feature PR, the old way. Merging it as it stands is fine: it would be the last release done like that.

Verified

• The changes filter's script, extracted from the workflow and run against a scratch repo:
  • Markdown-only, LICENSE, and app/layout/*.md changes → code=false
  • .zig, .yml + .md, and docs/demos/*.zon changes → code=true
  • an unfetchable push base and a workflow_dispatch → code=true
• The ci-ok script: success/skipped pass; any failure or cancelled fails.
• Both workflows parse (Ruby Psych). The ruleset is valid JSON. zig ast-check passes on the three edited Zig files.
• Live CI is this PR's own run, which takes the full matrix since it changes non-Markdown files. The merge_group path is untested until a queue is turned on.
• The ruleset JSON hasn't been posted. The ci-ok context and the OrganizationAdmin bypass (actor id 1) are as GitHub documents them.

Follow-ups

• Run zig build test-integration in CI (Linux) and add it to ci-ok. It is the suite most likely to catch a layout or drag regression, and nothing runs it today.
• Move the open plan PRs (Workspaces: many tabbed areas of documents, placed as views (plan, then steps) #225, Native windows plan: fizzy's backend between SDL and dvui, and the drag's glass in Liquid Glass #226) to issues with checklists, per the new rule.
• The next scaling step: automate store-plugin repins on an sdk-v* release (a dispatch that opens a repin PR in each plugin repo).
• Turn on the merge queue once two or more PRs a day land in parallel.

🤖 Generated with Claude Code