Devin Foley
b5f37f11eb
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work > - CONTRIBUTING.md and the PR template are the entry point for new contributors and set quality expectations for every PR > - Today they don't tell contributors to search for duplicate/related work first, don't require a linked GitHub issue, and don't spell out the merge bar (gates green + Greptile 5/5) > - Letting duplicate or under-reviewed PRs land creates extra work for reviewers and erodes quality > - This PR updates CONTRIBUTING.md and the PR template to require a search-first workflow, a linked issue, a clear merge bar, and explicit encouragement to help other contributors land their PRs > - The benefit is fewer duplicate PRs, easier triage, higher-quality merges, and a kinder collaboration culture ## What Changed - `CONTRIBUTING.md`: added a "Before You Start: Search First" section directing contributors to search GitHub for duplicate PRs and related issues, with a note that a fresh PR is okay if an old one is dead and would be painful to merge. - `CONTRIBUTING.md`: require every PR to link a GitHub issue in the body, plus references to related/duplicate PRs and issues. - `CONTRIBUTING.md`: added a section encouraging contributors to help finish other people's PRs, thank collaborators, and be kind. - `CONTRIBUTING.md`: tightened the merge bar — all Paperclip CI gates must be green and Greptile must be 5/5 with no open P2s, recommendations, or follow-ups. - `CONTRIBUTING.md` + `.github/PULL_REQUEST_TEMPLATE.md`: updated the thinking-path opener to "Paperclip is the open source app people use to manage AI agents for work" (consistent across examples and template). - `.github/PULL_REQUEST_TEMPLATE.md`: checklist gains items for duplicate/related search, linked issue, gates green, and the Greptile 5/5 bar. ## Verification - Docs-only change. Reviewed both files render correctly on GitHub. - No code or tests affected; no CI behavior change beyond the new checklist items contributors are asked to tick. ## Risks - Low risk. Documentation and template only — no runtime impact. Stricter contributor expectations may slow some PRs in the short term. ## Model Used - Claude, `claude-opus-4-7` (extended thinking, tool use). ## Related - Issue: #4188 — "Add issue templates and enforce issue-link check on PRs" (the linked-issue requirement here is a step toward what #4188 asks for, done in CONTRIBUTING/template rather than CI). - Prior PR: #4260 — "docs: expand CONTRIBUTING.md and add issue templates" (open; different scope — issue templates + broader expansion. This PR is narrower and focused on the search-first + merge-bar updates.) ## 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 linked the GitHub issue this PR addresses (and any related/duplicate issues) - [x] I have run tests locally and they pass (docs-only change; no tests to run) - [x] I have added or updated tests where applicable (N/A — docs) - [x] If this change affects the UI, I have included before/after screenshots (N/A — docs) - [x] I have updated relevant documentation to reflect my changes - [x] I have considered and documented any risks above - [ ] All Paperclip CI gates are green (will verify after push) - [ ] Greptile is 5/5 with no open P2s, recommendations, or follow-ups (pending review) - [x] I will address all Greptile and reviewer comments before requesting merge
92 lines
3.4 KiB
Markdown
92 lines
3.4 KiB
Markdown
## Thinking Path
|
||
|
||
<!--
|
||
Required. Trace your reasoning from the top of the project down to this
|
||
specific change. Start with what Paperclip is, then narrow through the
|
||
subsystem, the problem, and why this PR exists. Use blockquote style.
|
||
Aim for 5–8 steps. See CONTRIBUTING.md for full examples.
|
||
-->
|
||
|
||
> - Paperclip is the open source app people use to manage AI agents for work
|
||
> - [Which subsystem or capability is involved]
|
||
> - [What problem or gap exists]
|
||
> - [Why it needs to be addressed]
|
||
> - This pull request ...
|
||
> - The benefit is ...
|
||
|
||
## Linked Issues or Issue Description
|
||
|
||
<!--
|
||
Required. Pick ONE of the following two paths:
|
||
|
||
(A) Issue exists — tag each linked issue with `Fixes: #123`, `Closes #123`,
|
||
or `Refs #123`. Include duplicates and closely related issues too.
|
||
|
||
(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
|
||
• Feature: .github/ISSUE_TEMPLATE/feature_request.yml
|
||
• Adapter: .github/ISSUE_TEMPLATE/adapter_request.yml
|
||
|
||
See CONTRIBUTING.md → "Link Issues or Describe Them In-PR".
|
||
-->
|
||
|
||
-
|
||
|
||
## What Changed
|
||
|
||
<!-- Bullet list of concrete changes. One bullet per logical unit. -->
|
||
|
||
-
|
||
|
||
## Verification
|
||
|
||
<!--
|
||
How can a reviewer confirm this works? Include test commands, manual
|
||
steps, or both. For UI changes, include before/after screenshots.
|
||
-->
|
||
|
||
-
|
||
|
||
## Risks
|
||
|
||
<!--
|
||
What could go wrong? Mention migration safety, breaking changes,
|
||
behavioral shifts, or "Low risk" if genuinely minor.
|
||
-->
|
||
|
||
-
|
||
|
||
> For core feature work, check [`ROADMAP.md`](ROADMAP.md) first and discuss it in `#dev` before opening the PR. Feature PRs that overlap with planned core work may need to be redirected — check the roadmap first. See `CONTRIBUTING.md`.
|
||
|
||
## Model Used
|
||
|
||
<!--
|
||
Required. Specify which AI model was used to produce or assist with
|
||
this change. Be as descriptive as possible — include:
|
||
• Provider and model name (e.g., Claude, GPT, Gemini, Codex)
|
||
• Exact model ID or version (e.g., claude-opus-4-6, gpt-4-turbo-2024-04-09)
|
||
• Context window size if relevant (e.g., 1M context)
|
||
• Reasoning/thinking mode if applicable (e.g., extended thinking, chain-of-thought)
|
||
• Any other relevant capability details (e.g., tool use, code execution)
|
||
If no AI model was used, write "None — human-authored".
|
||
-->
|
||
|
||
-
|
||
|
||
## Checklist
|
||
|
||
- [ ] I have included a thinking path that traces from project context to this change
|
||
- [ ] I have specified the model used (with version and capability details)
|
||
- [ ] 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 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
|
||
- [ ] I have updated relevant documentation to reflect my changes
|
||
- [ ] I have considered and documented any risks above
|
||
- [ ] All Paperclip CI gates are green
|
||
- [ ] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
|
||
- [ ] I will address all Greptile and reviewer comments before requesting merge
|