From 57e60f5c054deade1bc171dda84b9ad39548e94c Mon Sep 17 00:00:00 2001 From: quotentiroler Date: Tue, 10 Feb 2026 00:33:24 -0800 Subject: [PATCH] Docs: consolidate maintainer PR workflow into PR_WORKFLOW.md --- .agents/skills/PR_WORKFLOW.md | 53 +++++++++++++++++++++++++++++++---- AGENTS.md | 20 ++----------- 2 files changed, 50 insertions(+), 23 deletions(-) diff --git a/.agents/skills/PR_WORKFLOW.md b/.agents/skills/PR_WORKFLOW.md index f75414181b..f091bfe12b 100644 --- a/.agents/skills/PR_WORKFLOW.md +++ b/.agents/skills/PR_WORKFLOW.md @@ -1,6 +1,11 @@ -# PR Review Instructions +# PR Workflow for Maintainers Please read this in full and do not skip sections. +This is the single source of truth for the maintainer PR workflow. + +## Triage order + +Process PRs **oldest to newest**. Older PRs are more likely to have merge conflicts and stale dependencies; resolving them first keeps the queue healthy and avoids snowballing rebase pain. ## Working rule @@ -9,9 +14,9 @@ Always pause between skills to evaluate technical direction, not just command su These three skills must be used in order: -1. `review-pr` -2. `prepare-pr` -3. `merge-pr` +1. `review-pr` — review only, produce findings +2. `prepare-pr` — rebase, fix, gate, push to PR head branch +3. `merge-pr` — squash-merge, verify MERGED state, clean up They are necessary, but not sufficient. Maintainers must steer between steps and understand the code before moving forward. @@ -31,6 +36,43 @@ Do not continue if you cannot verify the problem is real or test the fix. - Harden changes. Always evaluate security impact and abuse paths. - Understand the system before changing it. Never make the codebase messier just to clear a PR queue. +## Rebase and conflict resolution + +Before any substantive review or prep work, **always rebase the PR branch onto current `main` and resolve merge conflicts first**. A PR that cannot cleanly rebase is not ready for review — fix conflicts before evaluating correctness. + +- During `prepare-pr`: rebase onto `main` is the first step, before fixing findings or running gates. +- If conflicts are complex or touch areas you do not understand, stop and escalate. +- Prefer **rebase** for linear history; **squash** when commit history is messy or unhelpful. + +## Commit and changelog rules + +- Create commits with `scripts/committer "" `; avoid manual `git add`/`git commit` so staging stays scoped. +- Follow concise, action-oriented commit messages (e.g., `CLI: add verbose flag to send`). +- Group related changes; avoid bundling unrelated refactors. +- Changelog workflow: keep latest released version at top (no `Unreleased`); after publishing, bump version and start a new top section. +- When working on a PR: add a changelog entry with the PR number and thank the contributor. +- When working on an issue: reference the issue in the changelog entry. +- Pure test additions/fixes generally do **not** need a changelog entry unless they alter user-facing behavior or the user asks for one. + +## Co-contributor and clawtributors + +- If we squash, add the PR author as a co-contributor in the commit. +- If you review a PR and later do work on it, land via merge/squash (no direct-main commits) and always add the PR author as a co-contributor. +- When merging a PR: leave a PR comment that explains exactly what we did and include the SHA hashes. +- When merging a PR from a new contributor: run `bun scripts/update-clawtributors.ts` to add their avatar to the README "Thanks to all clawtributors" list, then commit the regenerated README. + +## Review mode vs landing mode + +- **Review mode (PR link only):** read `gh pr view`/`gh pr diff`; **do not** switch branches; **do not** change code. +- **Landing mode:** create an integration branch from `main`, bring in PR commits (**prefer rebase** for linear history; **merge allowed** when complexity/conflicts make it safer), apply fixes, add changelog (+ thanks + PR #), run full gate **locally before committing** (`pnpm build && pnpm check && pnpm test`), commit, merge back to `main`, then `git switch main` (never stay on a topic branch after landing). Important: contributor needs to be in git graph after this! + +## Pre-review safety checks + +- Before starting a review when a GH Issue/PR is pasted: run `git pull`; if there are local changes or unpushed commits, stop and alert the user before reviewing. +- PR review calls: prefer a single `gh pr view --json ...` to batch metadata/comments; run `gh pr diff` only when needed. +- PRs should summarize scope, note testing performed, and mention any user-facing changes or new flags. +- Read `docs/help/submitting-a-pr.md` ([Submitting a PR](https://docs.openclaw.ai/help/submitting-a-pr)) for what we expect from contributors. + ## Unified workflow Entry criteria: @@ -72,7 +114,7 @@ Stop and escalate instead of continuing if: Purpose: - Make the PR merge-ready on its head branch. -- Rebase onto current `main`, fix blocker/important findings, and run gates. +- Rebase onto current `main` first, then fix blocker/important findings, then run gates. Expected output: @@ -124,3 +166,4 @@ Maintainer checkpoint after merge: - Were any refactors intentionally deferred and now need follow-up issue(s)? - Did this reveal broader architecture or test gaps we should address? +- Run `bun scripts/update-clawtributors.ts` if the contributor is new. diff --git a/AGENTS.md b/AGENTS.md index 902a76db68..4e7397930e 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -90,34 +90,18 @@ ## Commit & Pull Request Guidelines +**Full maintainer PR workflow:** `.agents/skills/PR_WORKFLOW.md` -- triage order, quality bar, rebase rules, commit/changelog conventions, co-contributor policy, and the 3-step skill pipeline (`review-pr` > `prepare-pr` > `merge-pr`). + - Create commits with `scripts/committer "" `; avoid manual `git add`/`git commit` so staging stays scoped. - Follow concise, action-oriented commit messages (e.g., `CLI: add verbose flag to send`). - Group related changes; avoid bundling unrelated refactors. -- Changelog workflow: keep latest released version at top (no `Unreleased`); after publishing, bump version and start a new top section. -- PRs should summarize scope, note testing performed, and mention any user-facing changes or new flags. - Read this when submitting a PR: `docs/help/submitting-a-pr.md` ([Submitting a PR](https://docs.openclaw.ai/help/submitting-a-pr)) - Read this when submitting an issue: `docs/help/submitting-an-issue.md` ([Submitting an Issue](https://docs.openclaw.ai/help/submitting-an-issue)) -- PR review flow: when given a PR link, review via `gh pr view`/`gh pr diff` and do **not** change branches. -- PR review calls: prefer a single `gh pr view --json ...` to batch metadata/comments; run `gh pr diff` only when needed. -- Before starting a review when a GH Issue/PR is pasted: run `git pull`; if there are local changes or unpushed commits, stop and alert the user before reviewing. -- Goal: merge PRs. Prefer **rebase** when commits are clean; **squash** when history is messy. -- PR merge flow: create a temp branch from `main`, merge the PR branch into it (prefer squash unless commit history is important; use rebase/merge when it is). Always try to merge the PR unless it’s truly difficult, then use another approach. If we squash, add the PR author as a co-contributor. Apply fixes, add changelog entry (include PR # + thanks), run full gate before the final commit, commit, merge back to `main`, delete the temp branch, and end on `main`. -- If you review a PR and later do work on it, land via merge/squash (no direct-main commits) and always add the PR author as a co-contributor. -- When working on a PR: add a changelog entry with the PR number and thank the contributor. -- When working on an issue: reference the issue in the changelog entry. -- When merging a PR: leave a PR comment that explains exactly what we did and include the SHA hashes. -- When merging a PR from a new contributor: add their avatar to the README “Thanks to all clawtributors” thumbnail list. -- After merging a PR: run `bun scripts/update-clawtributors.ts` if the contributor is missing, then commit the regenerated README. ## Shorthand Commands - `sync`: if working tree is dirty, commit all changes (pick a sensible Conventional Commit message), then `git pull --rebase`; if rebase conflicts and cannot resolve, stop; otherwise `git push`. -### PR Workflow (Review vs Land) - -- **Review mode (PR link only):** read `gh pr view/diff`; **do not** switch branches; **do not** change code. -- **Landing mode:** create an integration branch from `main`, bring in PR commits (**prefer rebase** for linear history; **merge allowed** when complexity/conflicts make it safer), apply fixes, add changelog (+ thanks + PR #), run full gate **locally before committing** (`pnpm build && pnpm check && pnpm test`), commit, merge back to `main`, then `git switch main` (never stay on a topic branch after landing). Important: contributor needs to be in git graph after this! - ## Security & Configuration Tips - Web provider stores creds at `~/.openclaw/credentials/`; rerun `openclaw login` if logged out.