From dd51f6119cf9ef7130b615b82bd697fed17e54c8 Mon Sep 17 00:00:00 2001 From: argenis de la rosa Date: Wed, 4 Mar 2026 05:57:17 -0500 Subject: [PATCH] docs(contrib): align main-first PR base and overlap attribution --- .github/pull_request_template.md | 3 ++- CONTRIBUTING.md | 3 ++- docs/pr-workflow.md | 3 +++ 3 files changed, 7 insertions(+), 2 deletions(-) diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 084f2bf1a..fe3cd6f7d 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -2,7 +2,7 @@ Describe this PR in 2-5 bullets: -- Base branch target (`main` or `dev`; direct `main` PRs are allowed): +- Base branch target (`main` by default; use `dev` only when maintainers explicitly request integration batching): - Problem: - Why it matters: - What changed: @@ -27,6 +27,7 @@ Describe this PR in 2-5 bullets: - Closes # - Related # - Depends on # (if stacked) +- Existing overlapping PR(s) reviewed for this issue (list `# by @` or `N/A`): - Supersedes # (if replacing older PR) - Linear issue key(s) (required, e.g. `RMN-123`): - Linear issue URL(s): diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 7911e4b5d..bad9133fa 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -17,7 +17,8 @@ Welcome — contributions of all sizes are valued. If this is your first contrib - Fork the repository and clone your fork - Create a feature branch (`git checkout -b fix/my-change`) - Make your changes and run `cargo fmt && cargo clippy && cargo test` - - Open a PR against `dev` using the PR template + - Open a PR against `main` using the PR template (`dev` is used only when maintainers explicitly request integration batching) + - If the issue already has an open PR, coordinate there first or mark your PR with `Supersedes #...` plus attribution when replacing it 4. **Start with Track A.** ZeroClaw uses three [collaboration tracks](#collaboration-tracks-risk-based) (A/B/C) based on risk. First-time contributors should target **Track A** (docs, tests, chore) — these require lighter review and are the fastest path to a merged PR. diff --git a/docs/pr-workflow.md b/docs/pr-workflow.md index 438bbbc3a..a69302e4c 100644 --- a/docs/pr-workflow.md +++ b/docs/pr-workflow.md @@ -113,6 +113,8 @@ Maintain these branch protection rules on `dev` and `main`: ### 4.1 Step A: Intake - Contributor opens PR with full `.github/pull_request_template.md`. +- Normal contributor PR base is `main` by default; use `dev` only when maintainers explicitly request integration batching. +- If an issue already has open community PRs, reviewers/maintainers must acknowledge overlap and either continue that thread or document supersede rationale. - `PR Labeler` applies scope/path labels + size labels + risk labels + module labels (for example `channel:telegram`, `provider:kimi`, `tool:shell`) and contributor tiers by merged PR count (`trusted` >=5, `experienced` >=10, `principal` >=20, `distinguished` >=50), while de-duplicating less-specific scope labels when a more specific module label is present. - For all module prefixes, module labels are compacted to reduce noise: one specific module keeps `prefix:component`, but multiple specifics collapse to the base scope label `prefix`. - Label ordering is priority-first: `risk:*` -> `size:*` -> contributor tier -> module/path labels. @@ -227,6 +229,7 @@ We do **not** require contributors to quantify AI-vs-human line ownership. ### 8.2 Backlog pressure controls - If a new PR replaces an older open PR, require `Supersedes #...` and close the older one after maintainer confirmation. +- Replacement PRs must include attribution for materially integrated community work and explicitly state what was not carried forward. - Mark dormant/redundant PRs with `stale-candidate` or `superseded` to reduce duplicate review effort. ### 8.3 Issue triage discipline