From a2abebee075b07c037af19134aa8c7a2403e590b Mon Sep 17 00:00:00 2001 From: Devin Foley Date: Fri, 19 Jun 2026 10:14:24 -0700 Subject: [PATCH] docs: require descriptive, instance-free PR branch names (#8312) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work > - Contributions flow through GitHub PRs against `paperclipai/paperclip`, but most contributors author their work inside their own private Paperclip instance > - That tooling names a working branch after the internal issue/task — e.g. `PAPA-42-why-did-this-break` > - When that branch is pushed for a PR, the public PR's head branch carries instance-local context: it's not meaningful to reviewers and leaks instance-derived identifiers > - We just documented the issue-reference side of this (#8292), but said nothing about branch names > - This pull request adds a **Branch Naming** section to `CONTRIBUTING.md` and a matching PR-template checklist item, telling contributors to rename branches to descriptive, change-scoped names before pushing > - The benefit is public PRs whose branch names describe the change and contain no instance-local details ## Linked Issues or Issue Description Fixes: #8311 Refs: #8292 ## What Changed - `CONTRIBUTING.md`: new **Branch Naming** subsection — rename instance-named branches (e.g. `PAPA-42-...`) to descriptive, change-scoped, kebab-case names before pushing, with examples and the rename commands. - `.github/PULL_REQUEST_TEMPLATE.md`: new checklist item asserting the branch name describes the change and contains no internal ticket id or instance-derived details. ## Verification Docs-only change. Rendered Markdown locally and confirmed the new **Branch Naming** section and the new checklist item appear as intended. This PR's own branch (`docs/contributor-branch-naming`) follows the new guidance. No code paths affected. ## Risks Low risk — documentation and PR-template text only; no runtime, build, or schema impact. Automatically renaming branches at push time in the tooling is intentionally out of scope and tracked as separate follow-up work. ## Model Used Claude Opus 4.7 (claude-opus-4-7), extended thinking, agentic tool use via Claude Code. ## Checklist - [x] I have included a thinking path that traces from project context to this change - [x] I have specified the model used (with version and capability details) - [x] I have checked ROADMAP.md and confirmed this PR does not duplicate planned core work - [x] I have searched GitHub for duplicate or related PRs and linked them above - [x] I have either (a) linked existing issues with `Fixes: #` / `Closes #` / `Refs #` OR (b) described the issue in-PR following the relevant issue template - [x] I have not referenced internal/instance-local Paperclip issues or links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip` URLs) - [x] My branch name describes the change and contains no internal Paperclip ticket id or instance-derived details - [x] I have run tests locally and they pass - [ ] I have added or updated tests where applicable - [ ] If this change affects the UI, I have included before/after screenshots - [x] I have updated relevant documentation to reflect my changes - [x] I have considered and documented any risks above - [x] All Paperclip CI gates are green - [x] Greptile is 5/5 with no open P2s, recommendations, or follow-ups - [x] I will address all Greptile and reviewer comments before requesting merge Co-authored-by: Paperclip --- .github/PULL_REQUEST_TEMPLATE.md | 1 + CONTRIBUTING.md | 18 ++++++++++++++++++ 2 files changed, 19 insertions(+) diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index e11fa15f..a06a7c90 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -88,6 +88,7 @@ - [ ] I have searched GitHub for duplicate or related PRs and linked them above - [ ] I have either (a) linked existing issues with `Fixes: #` / `Closes #` / `Refs #` OR (b) described the issue in-PR following the relevant issue template - [ ] I have not referenced internal/instance-local Paperclip issues or links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip` URLs) +- [ ] My branch name describes the change (e.g. `docs/...`, `fix/...`) and contains no internal Paperclip ticket id or instance-derived details - [ ] I have run tests locally and they pass - [ ] I have added or updated tests where applicable - [ ] If this change affects the UI, I have included before/after screenshots diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 69de6e7b..3b6e6ef7 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -77,6 +77,24 @@ Do **not** include references to internal/instance-local Paperclip work, such as If an internal issue captured useful context, restate that context in plain English in the PR body instead of linking to it. +### Branch Naming + +Tooling (including Paperclip) often names a working branch after an internal issue and task — e.g. `PAPA-42-why-did-this-break`. That name leaks instance-local context, isn't meaningful to reviewers, and ends up as the public branch on your PR. + +Before you push, **rename the branch to something descriptive of the change itself**, not of your instance: + +- Use short, kebab-case names scoped to the change, optionally with a conventional prefix: `docs/no-internal-issue-references`, `fix/sandbox-secret-resolution`, `feat/adapter-retry-backoff`. +- Do **not** include internal Paperclip ticket ids (`PAPA-123`, `PAP-224`), instance task slugs, or other instance-derived details in the branch name. + +To rename and push under the new name: + +```bash +git branch -m +git push -u origin +# If your tooling already pushed the old branch, delete it from origin: +git push origin --delete +``` + ### Model Used (Required) Every PR must include a **Model Used** section specifying which AI model produced or assisted with the change. Include the provider, exact model ID/version, context window size, and any relevant capability details (e.g., reasoning mode, tool use). If no AI was used, write "None — human-authored". This applies to all contributors — human and AI alike.