Pull request

A pull request here is squash-merged into main, so its title becomes the commit subject on main and its body is the only narrative a later reader gets. Prepare both with the same care as the diff.

Before publishing

• Run the gates on the tree that will be pushed: just dev, just ci-rust, and the nightly clippy line CI uses. just ci-rust ends with assert_unchanged, so a codegen run that is not committed fails the gate; keep just codegen idempotent. CI runs just ci-rust under both a stable and a nightly toolchain, so the nightly half has to be run locally as cargo +nightly clippy --workspace --all-targets --all-features -- -D warnings.
• Run just ci-python for Python changes, just spdx-check for new files, and just link-license-check when the set of published crates changes. A skill lives in .agents/skills/<name>/SKILL.md, is symlinked from .github/skills/<name>, and carries license: "Apache-2.0" in its frontmatter instead of an SPDX header.
• A change that touches a feature gate is also checked in s3s-fs: the default build must not pull quinn or h3, and --features http3 must.
• Collect the evidence the body will cite: commands, exit codes, counts, and the source of every number (a gate, a measurement, a parity check).
• Keep one logical change per branch. A second concern rides in a second pull request, not in a second commit series.

Branch and history

• Name the branch <type>/<slug> with the same type the commits use: feat/, fix/, docs/, test/, refactor/, chore/.
• Branch from main, or from the branch the change builds on, and keep the history linear: the main ruleset requires linear history and the merge method is squash, so merge commits and "fix review" commits only enlarge the reviewer's diff.
• Fold a fix into the commit that owns the file and push with --force-with-lease. Rewriting your own unmerged branch is normal here; rewriting a branch someone else reviewed warrants a comment that says what moved.

Commits

• Follow Conventional Commits; the Git section of CONTRIBUTING.md points there.
• Scope with the crate or the area the change belongs to (s3s, s3s-fs, codegen, xtask, ci, deps, release, ...).
• The subject states the change; the body states why it is needed and what it makes true. Do not narrate the iterations that led to it.
• Mark a change that alters existing behaviour with ! after the type or scope (feat(s3s)!:) and describe the migration under ### Behavior.
• Add Assisted-by: <tool>:<model> when a tool wrote a substantive part of the change, and never add Signed-off-by on someone else's behalf; the AI Contribution Policy governs both.

Title and body

• Title: the subject of the squash commit, without a (#N) suffix — GitHub appends the number when it merges.
• Body: use these sections in this order and drop the ones that do not apply.
  • ### Summary — one paragraph: the problem, the change, and the number that shows the effect.
  • ### Changes — bullets, one per behavioural unit rather than one per file.
  • ### Behavior — what changes for a user or a caller, including deliberate breakages.
  • ### Tests — what ran, with exit codes or counts, plus any parity check or red control that shows the tests can fail.
  • ### References — the issues, upstream discussions or earlier pull requests the change answers. Write Part of #N while the issue still tracks other work: Fixes and Closes close it on merge.
  • ### Dependencies — what the change adds, removes or bumps, and anything the release order depends on.
  • ### AI — the tool and model that took part, what they did, and that a human reviewed the diff and owns the change.
• Open the pull request as a draft: the main ruleset runs a Copilot code review on drafts too. Convert it to ready when the checks are green and the description is complete.

What the checks will run

• CI runs on pull_request against main and feat/**, on merge_group, on a weekly schedule and on manual dispatch. skip-check is configured with paths_ignore: '["*.md"]', and status-check aggregates the jobs; that aggregate is the only check the ruleset requires.
• A pull request runs python, rust-msrv, rust (stable and nightly; the nightly leg is continue-on-error), cross-test (macOS and Windows), wasm-test and coverage.
• The seven e2e jobs (mint, s3-tests, boto3, rclone, s3s-e2e against silo or s3s-fs) carry if: github.event_name != 'pull_request': they run in the merge queue and on the schedule, never on the pull request. A pull request with every visible check green can therefore still fail the queue, so run the affected script under scripts/ before queueing it.
• Audit (dependency and license policy) runs when a manifest, the lockfile or .cargo/ changes; Fuzz when fuzz/, crates/ or its own workflow changes — on a pull request that is fuzz-check alone, because fuzz-run carries the same != 'pull_request' gate and fuzzes one rotating target per week on the schedule; Semver runs on every pull request and merge group.
• Code scanning uses GitHub's default setup. A very large diff can make it attribute pre-existing alerts to the pull request, and that check is not required: read code-scanning/alerts before treating it as a finding.

Landing

• main takes pull requests through the merge queue with the squash method; the queue re-runs CI, Audit and Semver on merge_group, and that is where the e2e jobs run for the first time. A queued pull request that fails the queue is dequeued rather than merged, so read the merge_group run before queueing it again.
• Merging does not delete the head branch, so clean up after it: once the pull request is merged, delete the head branch (remote and local) and remove the worktree instead of leaving a stale checkout behind.

Working with a review

• Treat a review comment as a question to settle, not a verdict to obey: answer with the artifact that settles it (a command, a file, a test) and state what changed.
• Reply on the line that was questioned, and say what changed.
• Either amend the commit that owns the change or append a commit that answers the review; both are accepted here. Pick the one that leaves the history easiest to read and mention which one you used.

Watching a pull request

Hang cargo run -p xtask -- watch-pr <PR#> in the background while a pull request is open, read its log when it exits and hang it again; the watch-pr skill covers the state line, the exit conditions, the restart discipline, and how to wait for checks alone with gh.

The public layer

Everything committed here, and everything pasted into a pull request, a review or a log, is public. Strip local paths, internal notes, tool- or machine-specific references, and personal data before they leave the machine, and keep a published tool self-contained: no dependency on a local checkout, no absolute path, no private context. A script that is brought into the repository is rewritten for that audience rather than copied.

What needs an explicit instruction

Pushing a branch, opening, undrafting, queueing or merging a pull request, dismissing a scanning alert, changing repository settings, deleting branches, and force-pushing a branch somebody else owns are actions to take only when the person responsible asks for them.