From 14a6fd3d1faa5bf3aa6c9321857741f4fe552305 Mon Sep 17 00:00:00 2001 From: KnowSky404 Date: Fri, 6 Nov 2026 14:57:53 +0800 Subject: [PATCH] docs: require worktree review and pull request workflow --- .github/pull_request_template.md | 10 ++++++++++ AGENTS.md | 13 ++++++++++++- CONTRIBUTING.md | 31 ++++++++++++++++++++++++++++++- 3 files changed, 52 insertions(+), 2 deletions(-) diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 05c276c1..fa220ee1 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -9,6 +9,8 @@ - [ ] This is one atomic change without unrelated refactors or formatting churn. - [ ] The change stays within N2API's personal, self-hosted V1 scope. - [ ] Commit messages use Conventional Commits. +- [ ] Development used a dedicated task branch and Git worktree. +- [ ] Local Codex `/review` (or `codex review --base `) covered the full PR diff before every push and PR creation; actionable findings are fixed. ## Verification @@ -18,6 +20,14 @@ Not run yet. ``` +## Review And Merge + + + ## Database And Migration - [ ] No database migration is required. diff --git a/AGENTS.md b/AGENTS.md index f49bf146..71e191a3 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -18,6 +18,17 @@ - Before claiming work is complete, review the diff and worktree state, run the relevant verification commands, and report the exact commands that passed. - Keep work scoped and incremental. Avoid bundling unrelated refactors into feature or bugfix changes. +## Worktree And Pull Request Workflow +- Apply this workflow to every repository change, including features, bug fixes, refactors, tests, documentation, configuration, and dependency updates, unless the user explicitly requests an exception. +- Before editing, inspect existing worktrees and preserve unrelated changes. Fetch the target branch and create a dedicated Git worktree with a task branch based on its current remote tip; reuse a worktree only when continuing the same task. Do not develop directly in the primary checkout or on `main`. +- Complete scoped implementation, relevant verification, and atomic Conventional Commits in the task worktree. Code or functionality changes still require the local Compose refresh below; documentation-only changes do not. +- Before every push and before creating a PR, run local Codex `/review` against the target branch and inspect the full PR diff. In a non-interactive session, use `codex review --base ` as the equivalent. Fix actionable findings, rerun affected verification, and repeat review until no actionable findings remain. Review must cover the exact changes being published; any subsequent change or rebase requires a new review. If review cannot run or fails, report the blocker and do not push or create the PR. +- Push the task branch and create a PR against the target branch after local review passes. Record the change, exact verification results, and local review outcome in the PR. This workflow is standing authorization for task-scoped branch pushes, PR creation, rebase merging, and deletion of the merged task branch; do not ask again unless the user narrows that authorization. It does not authorize direct pushes to `main`, tags, releases, production changes, or bypassing repository protections. +- Inspect automatic Codex bot review activity on the latest PR head, including reviews, inline comments, conversation comments, reactions, and pending activity. If automatically triggered, wait for completion and address actionable findings before merging. Fixes return through local verification, local `/review`, and push; recheck automatic review and CI on the updated head. Never manually trigger the bot, post `@codex review`, or request it as a reviewer. +- If no automatic Codex review was triggered, proceed to rebase merge once CI and repository requirements pass; do not wait indefinitely or summon the bot. Missing review output alone does not mean the bot was not triggered: pending or running activity must finish, and failed or inaccessible status must be reported rather than treated as approval. +- Before merging, confirm the PR head is still the reviewed head, no actionable review findings remain, and required checks pass. Use GitHub rebase merge, never squash or a merge commit, and do not bypass protections. If conflicts require a local rebase, resolve them in the task worktree, rerun verification and local `/review`, then push with `--force-with-lease` only for that task branch and recheck the updated PR. +- After confirming the PR was merged, delete its remote task branch, remove the clean task worktree, and delete the local task branch. Preserve uncommitted work and other tasks' worktrees or branches. Fast-forward the primary checkout only when clean and safe, and verify the resulting target-branch CI as required below. Report the PR, merge result, checks, and cleanup; if blocked, retain the branch/worktree and report the actual blocker. + ## Project Direction - N2API is a personal AI API/account gateway inspired by sub2api's user experience, not a fork of sub2api. - Do not copy source code from `Wei-Shaw/sub2api`; only use it as product and behavior reference. @@ -88,7 +99,7 @@ - After each atomic change (each feature, fix, refactor, docs update, or test update), you MUST create an atomic git commit. Never accumulate multiple unrelated changes into one commit, and never leave a change uncommitted after it is complete unless the user explicitly asks otherwise. - Each commit MUST contain exactly one coherent change: for example, one feature, one fix, one refactor, one docs update, or one test update. - Use Conventional Commits for commit messages, such as `feat: add provider health check`, `fix: preserve streaming response headers`, `docs: update deployment guide`, `test: cover token refresh`, or `chore: update tooling`. -- Do not push commits or tags, merge remote branches, create pull requests, publish releases, or otherwise send local changes to GitHub unless the user explicitly requests that remote action. A request to implement or commit changes does not imply permission to push. +- Follow the standing authorization and review gates in **Worktree And Pull Request Workflow** for task branches and PRs. Other remote writes, tags, releases, and repository-setting changes require an explicit user request. - Do not commit generated build artifacts, dependency directories, local caches, or real environment files. - After every conversation turn that involves code or functionality changes, rebuild and refresh the local Docker Compose dev stack so the user can test and verify. Use the `n2api-refresh-docker` skill for the exact commands. If no code or functionality was changed during the turn, skip this step. - Because the local Compose refresh uses `--no-cache`, run `docker builder prune --all --force` immediately before the rebuild to remove unused cache from previous builds and again after a successful rebuild, recreation, and verification so the new build cache does not accumulate. This cleanup is builder-wide. Do not automatically run `docker system prune`, prune images, or prune volumes. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 76c158d7..69af671f 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -18,7 +18,10 @@ source code from `Wei-Shaw/sub2api`. 1. Read `AGENTS.md`, `README.md`, `docs/README.md`, and the relevant design or operations plan. -2. Check the current worktree and preserve unrelated changes. +2. Inspect existing worktrees and preserve unrelated changes. Fetch the target + branch and create a dedicated task branch and Git worktree from its current + remote tip before editing; reuse a worktree only to continue the same task. + Do not develop in the primary checkout or directly on `main`. 3. Reproduce bugs before changing behavior. 4. Keep one coherent behavior, fix, documentation update, or test update per change. @@ -58,6 +61,32 @@ fixtures, logs, screenshots, traces, artifacts, issues, or pull requests. ## Commits And Pull Requests +Follow [AGENTS.md](AGENTS.md#worktree-and-pull-request-workflow) for every +repository change, including documentation, configuration, tests, and dependency +updates, unless the user explicitly requests an exception: + +1. Implement and verify the scoped change in its task worktree, then make atomic + Conventional Commits. +2. Before every push and before creating a PR, run local Codex `/review` against + the target branch, or `codex review --base ` non-interactively. + Review the full PR diff, fix actionable findings, rerun affected verification, + and repeat review until clear. Any later change or rebase requires review + again; a failed or unavailable review blocks publication. +3. Push the task branch and create a PR with the exact verification results and + local review outcome. The project workflow authorizes these task-scoped + actions, rebase merging, and merged-branch cleanup without repeated approval. +4. Check automatic Codex bot review on the latest PR head. If triggered, wait + for completion, fix actionable findings, and repeat local verification, + `/review`, push, and remote checks. Never manually trigger or request the bot. + If it was not triggered, proceed once CI and repository requirements pass. + Pending, running, failed, or inaccessible review activity is not a clean + review or evidence that no review was triggered. +5. Confirm the reviewed PR head and passing checks, then rebase merge without + bypassing protections. After merge confirmation, delete the remote task + branch, remove its clean worktree, and delete the local task branch. Preserve + unrelated work, update the primary checkout only when safe, and verify the + target-branch CI. Report any blocker instead of skipping a gate. + - Make atomic changes and exclude unrelated refactors or formatting churn. - Use Conventional Commits, for example `fix(gateway): bound response reads`, `test(store): cover token cleanup`, or `docs(governance): add security policy`.