From 8a062be94d172f9e97636e1cf913f038aac875cf Mon Sep 17 00:00:00 2001 From: Devin Foley Date: Thu, 18 Jun 2026 14:37:21 -0700 Subject: [PATCH] docs: forbid internal Paperclip issue references in PRs (#8293) 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 > - Those instances mint instance-local issue ids and deep links (`PAPA-123`, `/PAP/issues/...`, `agent://...`, localhost/tailnet URLs) that only the author can open > - When contributors paste those references into a public PR, reviewers hit clutter and broken links and have to ask for cleanup > - There was no written guidance telling contributors (human or agent) to keep those references out > - This pull request adds that guidance to `CONTRIBUTING.md` and surfaces it as a PR-template checklist item plus an inline hint > - The benefit is cleaner PRs that reference only public, openable GitHub issues/PRs, with internal context restated in plain English ## Linked Issues or Issue Description Fixes: #8292 ## What Changed - `CONTRIBUTING.md`: new **No Internal Issue References** subsection explaining what to leave out (internal ticket ids, instance UI/deep links, localhost/tailnet URLs) and to restate useful context in plain English; added a cross-reference sentence from the existing "Link Issues or Describe Them In-PR" guidance. - `.github/PULL_REQUEST_TEMPLATE.md`: new checklist item, plus an inline hint in the Linked Issues comment block, directing contributors to reference only public GitHub issues/PRs. ## Verification Docs-only change. Rendered Markdown locally and confirmed the new `#no-internal-issue-references` anchor resolves from the cross-reference link, and that the template checklist item appears in the rendered list. No code paths affected. ## Risks Low risk — documentation and PR-template text only; no runtime, build, or schema impact. An optional automated CI gate was intentionally deferred to a follow-up to avoid regex false positives. ## 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] 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 - [ ] 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 | 7 +++++++ CONTRIBUTING.md | 16 +++++++++++++++- 2 files changed, 22 insertions(+), 1 deletion(-) diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index 6221ffdb..e11fa15f 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -22,6 +22,12 @@ (A) Issue exists — tag each linked issue with `Fixes: #123`, `Closes #123`, or `Refs #123`. Include duplicates and closely related issues too. + Only reference PUBLIC GitHub issues/PRs here. Do NOT paste internal, + instance-local Paperclip references — ticket ids like PAPA-123 / PAP-224, + /PAP/issues/... or agent://... links, or localhost/tailnet URLs. Other + contributors cannot open them. See CONTRIBUTING.md → "No Internal Issue + References". + (B) No issue exists — describe the underlying problem here, following the relevant issue template so reviewers get the same fields: • Bug: .github/ISSUE_TEMPLATE/bug_report.yml @@ -81,6 +87,7 @@ - [ ] I have checked ROADMAP.md and confirmed this PR does not duplicate planned core work - [ ] 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) - [ ] 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 2c43a072..69de6e7b 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -61,7 +61,21 @@ We do not gate PRs on a pre-existing issue. Two acceptable paths: - **Feature:** problem/motivation, proposed solution, alternatives considered, roadmap alignment. See [`feature_request.yml`](.github/ISSUE_TEMPLATE/feature_request.yml). - **New adapter:** agent or provider, why it's useful, how it's invoked. See [`adapter_request.yml`](.github/ISSUE_TEMPLATE/adapter_request.yml). -Either way, a reviewer should be able to understand the underlying issue without leaving the PR. Commitperclip may check that one of these two paths is satisfied. +Either way, a reviewer should be able to understand the underlying issue without leaving the PR. Commitperclip may check that one of these two paths is satisfied. Only link **public** GitHub issues — see [No Internal Issue References](#no-internal-issue-references) for what to leave out. + +### No Internal Issue References + +Many contributors run their own Paperclip instance to manage their work. Issue ids and links from *your* instance are private — reviewers and other contributors cannot open them, so they show up as clutter or broken links. + +In your PR title, description, commits, and comments, **only reference public GitHub issues and PRs** — `#123`, `Fixes #123` / `Closes #123` / `Refs #123`, or full `https://github.com/paperclipai/paperclip/...` URLs. + +Do **not** include references to internal/instance-local Paperclip work, such as: + +- Internal ticket ids like `PAPA-123`, `PAP-224`, or any `{PREFIX}-{NUMBER}` identifier that isn't a public GitHub issue number. +- Instance UI links such as `/PAP/issues/...`, `/PAP/agents/...`, `agent://...`, or document deep links. +- `localhost`, private IP, or tailnet URLs pointing at your own instance. + +If an internal issue captured useful context, restate that context in plain English in the PR body instead of linking to it. ### Model Used (Required)