Skip to content

filing-pull-requests.md

Latest commit

 

History

History
192 lines (128 loc) · 9.58 KB

filing-pull-requests.md

File metadata and controls

192 lines (128 loc) · 9.58 KB

Filing Pull Requests

Related: filing issues, versioning, kernel skill aiwg-pr (run aiwg show skill aiwg-pr)

A high-quality PR is focused, verified, policy-compliant, and reaches main with green CI. This guide covers the AIWG-specific delivery rules — branching strategy, the no-attribution rule, the CI-green-before-done discipline, and the release-time obligations.

Pre-flight: delivery policy

Before you create a branch or open a PR, read the project's .aiwg/aiwg.config delivery.mode. Three modes, three workflows:

Mode Branch PR Closing
direct No — commit straight to default_branch No PR Closes #N in commit message
feature-branch Branch per issue No PR Closes #N in commit on the branch
pr-required Branch per issue Required Closes #N in PR body 
aiwg config get --project delivery.mode
# or
cat .aiwg/aiwg.config | jq -r '.delivery.mode'

If mode: direct, do not open a PR. Commit directly to main with Closes #N in the message. The delivery-policy rule (kernel rule, always loaded) is authoritative.

The AIWG repo runs in direct mode — the May-2026 fix sweep (commits 6500e167, 497fcca7, 3f2b557b, d052aa2f, a50c1d76, ac61a2b8) landed straight to main with Closes #N per commit.

The walkthrough

1. Find or file the issue first

Every PR closes (or refs) an issue. If you don't have one:

  • Search for existing matches: aiwg run skill steward-prep-delivery -- "<topic>"
  • If none match, file via filing issues before drafting the PR

2. Branch (only for non-direct modes)

git checkout -b fix/{issue-number}-{slug}
# slug: short, lowercase, hyphenated derivation of the issue title

For direct mode, skip this step.

3. Make the change

Stay focused on the linked issue. Anti-patterns to avoid:

  • "While I'm at it" — adding unrelated changes. Split into separate PRs/commits.
  • Reformatting unrelated files mid-PR — send formatting as its own PR.
  • Adding new dependencies without justification — note why in the PR body.

4. Verification (REQUIRED before commit)

Check Command Pass criterion
Typecheck npx tsc --noEmit Clean (no output)
Tests npm test All pass (or only pre-existing flaky perf tests fail; document the latter)
Lint npm exec markdownlint-cli2 (for docs) Clean
Build npm run build:cli Succeeds (catches dist/ vs src/ path drift)

Don't skip these. The CI-failure-then-fix cycle in 497fcca7 → 3f2b557b was caused by skipping the local test run before push. Two pushes, one wasted CI cycle, easily prevented.

5. Commit message

Use conventional commits: type(scope): subject

fix(area): one-line subject

Body explains WHY, not just what. The diff already shows what.
Reference the linked issue; for `direct` mode include `Closes #N`
so the issue auto-closes on push.

Verification:
- npx tsc --noEmit clean
- npm test — 6306 pass, 1 pre-existing flake (cli-perf cold-start)
- Manual: <smoke-test description>

Closes #N

Conventional commit types: feat, fix, chore, docs, refactor, test, perf, ci, build. Scope is the area (e.g., steward, sdlc,release, cli,docs).

6. No AI attribution

The project no-attribution rule is universal across platforms. The commit/tag/PR body must not contain:

  • Co-Authored-By: Claude <…> (or any AI tool)
  • Generated with [Claude Code] / "Generated by Codex" / "Written by GitHub Copilot"
  • 🤖 emoji or any tool branding

The AI is a tool. Tools don't sign their output.

7. Push

# For direct mode
git push origin main

# For feature-branch / pr-required
git push origin fix/{issue-number}-{slug}

8. Open the PR (only for pr-required mode)

Use the template at .gitea/pull_request_template.md (or .github/pull_request_template.md). Required sections:

  • Summary — one paragraph: what changed and why
  • Linked issues — Closes #N / Refs #N
  • Changes — bullets of meaningful changes (not file count)
  • Verification — filled-in checklist showing typecheck/test/CI status
  • Risk and rollback — even if "low / git revert"
  • Policy reminders — delivery mode + no-attribution + CI-green-before-done

The body should be agent-readable: clear sections, specific paths, no marketing speak.

9. CI green before done

A commit isn't done until CI is green. After push, wait for the run on origin (Gitea). AIWG CI takes ~2 minutes.

If it fails:

  1. Diagnose the failure
  2. Fix the underlying issue — no || true, no continue-on-error: true, no test deletion. See anti-laziness and dev-pipeline-safety rules.
  3. Commit the fix and wait again
  4. Don't declare the work done until green

Never leave main in a red state.

10. After merge (pr-required) or push (direct)

  • The linked issue auto-closes via Closes #N
  • If you imported a cross-tracker report, thank the original reporter in a closing comment on the source tracker (see filing issues § import flow)
  • Update CHANGELOG.md if the change is user-visible — for releases, the flow-release skill handles this; for individual PRs that ship before the release, append to the unreleased section

Release-time PRs

When the PR is part of a release sequence, the flow-release skill handles the orchestration. The PR itself follows the same rules as any other PR, but the release flow adds extra gates:

  • Version bump (package.json + CHANGELOG.md + docs/releases/v{version}-announcement.md)
  • UAT for stable channel: npm run uat — all 9 tests must pass
  • Tag creation, push to origin, optional GitHub mirror push
  • npm dist-tag promotion

See flow-release for the full sequence. The .aiwg/release.config declares which gates apply.

Anti-patterns to avoid

  • AI attribution lines — never. Universal rule.
  • --no-verify or --no-gpg-sign — never bypass hooks. Fix the underlying issue.
  • continue-on-error: true on tests — never silence the smoke detector. See dev-pipeline-safety.
  • Skipping CI green wait — if CI fails, fix it before declaring done.
  • Bundling unrelated changes — split into focused PRs.
  • Workarounds instead of root-cause fixes — see anti-laziness Rule 9: "real fix over workaround".
  • Closes #N in a PR body for direct mode — wrong; use the commit message instead.

When stuck

If the verification gates fail and you can't fix them in 3 attempts, escalate per the anti-laziness recovery protocol. Don't take destructive shortcuts (skip tests, weaken assertions, etc.).

Quick reference

Need to Run
Check delivery mode aiwg config get --project delivery.mode
Verify locally before push npx tsc --noEmit && npm test && npm run build:cli
Run UAT (release prep) npm run uat
Fetch full PR guide aiwg show skill aiwg-pr
Drive a release aiwg show skill flow-release

Related