Skip to content

The open-source app everyone uses to manage agents at work

docs: require descriptive, instance-free PR branch names (#8312)

Devin Foleya2abebee075b
diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md
index e11fa15f03..a06a7c9051 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 69de6e7bba..3b6e6ef729 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 <descriptive-name>
+git push -u origin <descriptive-name>
+# If your tooling already pushed the old branch, delete it from origin:
+git push origin --delete <old-name>
+```
+
### 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.