From b8153c1ad4f1b7829b4de3bc10cce6dd02adce3d Mon Sep 17 00:00:00 2001 From: bo Date: Fri, 31 Jul 2026 23:48:09 +0800 Subject: [PATCH 1/2] docs: complete pull request workflow --- .github/pull_request_template.md | 1 + AGENTS.md | 10 ++++++---- CONTRIBUTING.md | 22 ++++++++++++++++++++-- 3 files changed, 27 insertions(+), 6 deletions(-) diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 0aa3d534..f750f853 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -13,6 +13,7 @@ - [ ] `bun run typecheck` - [ ] `bun run test` - [ ] `bun run build` when the production package or Web UI is affected +- [ ] `git diff --check` ## Documentation and security diff --git a/AGENTS.md b/AGENTS.md index e759f57e..627d5684 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -520,11 +520,13 @@ HTTP Streamable only. Built-in: context7, grep.app, exa (hardcoded in `BUILTIN_M ## Repository GitHub Workflow - `main` is protected and accepts changes through pull requests only. Never commit or push directly to `main`. -- Start repository work from the latest `origin/main` on a focused feature branch. Keep branch creation, commit, push, PR creation, and merge as explicit, separately reported actions. -- Before opening a PR, run the relevant local validation documented in `CONTRIBUTING.md`. +- Start repository work from the latest `origin/main` on a focused feature branch. Branch creation, commit, push, opening or marking a PR ready, and merge are distinct state-changing actions: perform only the actions the user requested, unless they explicitly requested the complete end-to-end PR lifecycle, and report each completed state precisely. +- Before opening a PR, inspect the staged scope and run the relevant local validation documented in `CONTRIBUTING.md`, including `git diff --check`. Open a ready PR against `main` and complete the repository PR template when the change is ready for review. - The required GitHub gates are the `Verify` status check and the CodeQL code-scanning policy. `Verify` installs with the frozen lockfile, typechecks, runs tests with diagnostics, builds the production binary, and smoke-tests that binary. -- CodeRabbit and Cubic provide automatic advisory review on ready PRs and incremental pushes. Address actionable findings and resolve every review conversation, but final merge judgment remains human. -- Merge PRs with squash merge only. Do not bypass repository rules, force-push shared branches, or weaken required checks to unblock a change. +- CodeRabbit and Cubic provide automatic advisory review on ready PRs and incremental pushes. After every pushed change, wait for checks and reviews on the new head SHA, inspect review conversations again, address or explain actionable findings, rerun relevant validation, and repeat until the latest head is clear. A pending AI reviewer is neither a failure nor permission to merge. +- Immediately before merge, record the current head SHA and confirm that it is still the reviewed head, the PR is mergeable, `Verify` and CodeQL pass, every review conversation is resolved, and the user has authorized the merge. Merge with squash only. Do not bypass repository rules, force-push shared branches, or weaken required checks to unblock a change. +- After merge, fetch the remote, switch to local `main`, fast-forward it with `git merge --ff-only origin/main`, and verify that local `main` matches `origin/main` with a clean worktree. Report the merge commit and synchronized state separately from PR creation. +- Release work follows the same PR loop, then verifies that the release tag points to the exact merged commit, the release workflow succeeds, the public Release and expected assets exist, and local `main` is synchronized. A green PR or a pushed tag alone is not a completed release. ## Testing Patterns diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 9ab777df..5c5b864b 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -68,6 +68,7 @@ Validation order is `typecheck` before `test`. ```sh bun run typecheck bun run test +git diff --check ``` For changes that affect the production package or Web UI, also run: @@ -93,8 +94,25 @@ They may add incremental feedback after new commits are pushed. Address actionable findings, explain intentional decisions when appropriate, and do not treat an AI approval as a substitute for maintainer judgment. -Maintainers merge accepted PRs with squash merge. The merged PR becomes one -commit on `main`, and GitHub deletes the merged head branch automatically. +Checks and reviews apply to the current PR head. After every pushed fix, rerun +the relevant local validation, wait for `Verify`, CodeQL, CodeRabbit, and Cubic +on the new head commit, and inspect review conversations again. A pending AI +review is neither a failure nor a merge-ready result. + +Immediately before merge, maintainers confirm that the reviewed head commit has +not changed, the PR is mergeable, required gates pass, and every review +conversation is resolved. Maintainers merge accepted PRs with squash merge. +The merged PR becomes one commit on `main`, and GitHub deletes the merged head +branch automatically. + +After merge, synchronize the local default branch without rewriting it: + +```sh +git fetch origin +git switch main +git merge --ff-only origin/main +git status --short --branch +``` ## Code conventions From 1d05fd078bb09a21ea57554dd0b82b5a15be3d72 Mon Sep 17 00:00:00 2001 From: bo Date: Sat, 1 Aug 2026 00:05:01 +0800 Subject: [PATCH 2/2] docs: fix PR workflow validation guidance --- .github/pull_request_template.md | 2 +- AGENTS.md | 6 +++--- CONTRIBUTING.md | 8 +++++++- 3 files changed, 11 insertions(+), 5 deletions(-) diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index f750f853..7d584b26 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -13,7 +13,7 @@ - [ ] `bun run typecheck` - [ ] `bun run test` - [ ] `bun run build` when the production package or Web UI is affected -- [ ] `git diff --check` +- [ ] `git diff --check origin/main...HEAD` (`upstream/main...HEAD` for forks) ## Documentation and security diff --git a/AGENTS.md b/AGENTS.md index 627d5684..862e40e0 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -520,12 +520,12 @@ HTTP Streamable only. Built-in: context7, grep.app, exa (hardcoded in `BUILTIN_M ## Repository GitHub Workflow - `main` is protected and accepts changes through pull requests only. Never commit or push directly to `main`. -- Start repository work from the latest `origin/main` on a focused feature branch. Branch creation, commit, push, opening or marking a PR ready, and merge are distinct state-changing actions: perform only the actions the user requested, unless they explicitly requested the complete end-to-end PR lifecycle, and report each completed state precisely. -- Before opening a PR, inspect the staged scope and run the relevant local validation documented in `CONTRIBUTING.md`, including `git diff --check`. Open a ready PR against `main` and complete the repository PR template when the change is ready for review. +- Start repository work from the latest canonical `main` (`origin/main` for collaborators, `upstream/main` for forks) on a focused feature branch. Branch creation, commit, push, opening or marking a PR ready, and merge are distinct state-changing actions: perform only the actions the user requested, unless they explicitly requested the complete end-to-end PR lifecycle, and report each completed state precisely. +- Before opening a PR, inspect the staged scope and run the relevant local validation documented in `CONTRIBUTING.md`, including `git diff --check origin/main...HEAD` (or `upstream/main...HEAD` for forks). Open a ready PR against `main` and complete the repository PR template when the change is ready for review. - The required GitHub gates are the `Verify` status check and the CodeQL code-scanning policy. `Verify` installs with the frozen lockfile, typechecks, runs tests with diagnostics, builds the production binary, and smoke-tests that binary. - CodeRabbit and Cubic provide automatic advisory review on ready PRs and incremental pushes. After every pushed change, wait for checks and reviews on the new head SHA, inspect review conversations again, address or explain actionable findings, rerun relevant validation, and repeat until the latest head is clear. A pending AI reviewer is neither a failure nor permission to merge. - Immediately before merge, record the current head SHA and confirm that it is still the reviewed head, the PR is mergeable, `Verify` and CodeQL pass, every review conversation is resolved, and the user has authorized the merge. Merge with squash only. Do not bypass repository rules, force-push shared branches, or weaken required checks to unblock a change. -- After merge, fetch the remote, switch to local `main`, fast-forward it with `git merge --ff-only origin/main`, and verify that local `main` matches `origin/main` with a clean worktree. Report the merge commit and synchronized state separately from PR creation. +- After merge, fetch the canonical remote, switch to local `main`, fast-forward it from that remote's `main`, and verify that both refs match with a clean worktree. Report the merge commit and synchronized state separately from PR creation. - Release work follows the same PR loop, then verifies that the release tag points to the exact merged commit, the release workflow succeeds, the public Release and expected assets exist, and local `main` is synchronized. A green PR or a pushed tag alone is not a completed release. ## Testing Patterns diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 5c5b864b..00fbf1aa 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -68,9 +68,12 @@ Validation order is `typecheck` before `test`. ```sh bun run typecheck bun run test -git diff --check +git diff --check origin/main...HEAD ``` +The command above uses `origin` for the canonical repository. Replace it with +`upstream` when contributing from a fork. + For changes that affect the production package or Web UI, also run: ```sh @@ -107,6 +110,9 @@ branch automatically. After merge, synchronize the local default branch without rewriting it: +The commands below use `origin` for the canonical repository. Replace it with +`upstream` when contributing from a fork. + ```sh git fetch origin git switch main