master
8 Commits
| Author | SHA1 | Message | Date | |
|---|---|---|---|---|
 Devin Foley
|
254b01d2af |
docs: drop contributor screenshot requirement in favor of cutter.sh bot (#8409)
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work > - Contributors follow `CONTRIBUTING.md` and the PR template when opening pull requests > - Those docs still tell contributors to manually capture and attach before/after screenshots for UI changes > - That requirement is now redundant: the `cutter.sh` bot automatically captures and posts before/after UI screenshots to every PR > - Asking contributors to also do it by hand adds friction and produces duplicate screenshots > - This pull request removes the manual screenshot obligation from `CONTRIBUTING.md` and the PR template, and documents that `cutter.sh` handles it > - The benefit is a clearer, lower-friction contribution flow that matches how screenshots actually get posted today ## Linked Issues or Issue Description No public GitHub issue. Underlying change: Our contributor docs and PR template instructed contributors to attach before/after screenshots for any UI change. We now run a bot (`cutter.sh`) that automatically captures and posts before/after UI screenshots to the PR, so the manual step is no longer needed. This change removes the manual requirement and instead documents that the bot handles screenshots, asking contributors to simply describe the visible change. ## What Changed - `CONTRIBUTING.md`: removed the "Before / After screenshots" requirement from the Path 2 PR checklist and from the "Writing a Good PR message" section; both now explain that the `cutter.sh` bot posts UI screenshots automatically and ask contributors to describe the visible change instead. - `.github/PULL_REQUEST_TEMPLATE.md`: updated the Verification guidance to note that `cutter.sh` posts before/after screenshots automatically, and removed the "include before/after screenshots" item from the checklist. - Issue templates were intentionally left unchanged — they only offer screenshots as an optional "if helpful" field, never a requirement. ## Verification - Docs-only change; no code paths affected. - `grep -rin "screenshot" CONTRIBUTING.md .github/` confirms no screenshot *requirement* remains — only the new `cutter.sh` wording and the optional "if helpful" fields in issue templates. - Render `CONTRIBUTING.md` and the PR template to confirm the wording reads cleanly. ## Risks Low risk — documentation-only change. No build, runtime, or migration impact. ## Model Used Claude (Anthropic), model `claude-opus-4-8`, extended thinking with tool use. ## 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 (e.g. `docs/...`, `fix/...`) and contains no internal Paperclip ticket id or instance-derived details - [x] I have run tests locally and they pass (docs-only; no tests apply) - [ ] I have added or updated tests where applicable (N/A — docs-only) - [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 (pending CI) - [ ] 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 |
||
|
Devin Foley
|
a2abebee07 |
docs: require descriptive, instance-free PR branch names (#8312)
## 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 <noreply@paperclip.ing> |
||
|
Devin Foley
|
8a062be94d |
docs: forbid internal Paperclip issue references in PRs (#8293)
## 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 <noreply@paperclip.ing> |
||
|
Devin Foley
|
b5f37f11eb |
docs(contributing): search-first, linked issue, gates + Greptile bar (#7522)
## 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 |
||
|
Devin Foley
|
e458145583 |
docs: add public roadmap and update contribution policy for feature PRs (#3835)
## Thinking Path > - Paperclip orchestrates AI agents for zero-human companies > - As the project grows, more contributors want to build features — which is great > - Without a public roadmap or clear contribution guidance, contributors spend time on PRs that overlap with planned core work > - This creates frustration on both sides when those PRs can't be merged > - This PR publishes a roadmap, updates the contribution guide with a clear path for feature proposals, and reinforces the workflow in the PR template > - The benefit is that contributors know exactly how to propose features and where to focus for the highest-impact contributions ## What Changed - Added `ROADMAP.md` with expanded descriptions of all shipped and planned milestones, plus guidance on coordinating feature contributions - Added "Feature Contributions" section to `CONTRIBUTING.md` explaining how to propose features (check roadmap → discuss in #dev → consider the plugin system) - Updated `.github/PULL_REQUEST_TEMPLATE.md` with a callout linking to the roadmap and a new checklist item to check for overlap with planned work, while preserving the newer required `Model Used` section from `master` - Added `Memory / Knowledge` to the README roadmap preview and linked the preview to the full `ROADMAP.md` ## Verification - Open `ROADMAP.md` on GitHub and confirm it renders correctly with all milestone sections - Read the new "Feature Contributions" section in `CONTRIBUTING.md` and verify all links resolve - Open a new PR and confirm the template shows the roadmap callout and the new checklist item - Verify README links to `ROADMAP.md` and the roadmap preview includes "Memory / Knowledge" ## Risks - Docs-only change — no runtime or behavioral impact - Contribution policy changes were written to be constructive and to offer clear alternative paths (plugins, coordination via #dev, reference implementations as feedback) ## Model Used - OpenAI Codex local agent (GPT-5-based coding model; exact runtime model ID is not exposed in this environment) - Tool use enabled for shell, git, GitHub CLI, and patch application - Used to rebase the branch, resolve merge conflicts, update the PR metadata, and verify the repo state ## 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 - [ ] I have run tests locally and they pass - [ ] I have added or updated tests where applicable (N/A — docs only) - [ ] If this change affects the UI, I have included before/after screenshots (N/A — no UI changes) - [x] I have updated relevant documentation to reflect my changes - [x] I have considered and documented any risks above - [x] I will address all Greptile and reviewer comments before requesting merge --------- Co-authored-by: Paperclip <noreply@paperclip.ing> |
||
|
Devin Foley
|
c041fee6fc |
feat: add Model Used section to PR template and checklist
Add a required "Model Used" section to the PR template so contributors document which AI model (with version, context window, reasoning mode, and other capability details) was used for each change. Also adds a corresponding checklist item. Co-Authored-By: Paperclip <noreply@paperclip.ing> |
||
|
Devin Foley
|
5222a49cc3 |
chore: expand thinking path placeholder for depth
Address Greptile feedback — the sparse 3-line placeholder could lead to shallow thinking paths. Expanded to 6 lines with guiding brackets and added "Aim for 5–8 steps" hint in the comment. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> |
||
|
Devin Foley
|
36574bd9c6 |
chore: add GitHub PR template
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> |