dda63a4324
## Thinking Path > - Paperclip orchestrates AI agents for zero-human companies > - Contributors submit pull requests to improve the codebase > - We have a PR template at `.github/PULL_REQUEST_TEMPLATE.md` that standardizes PR descriptions > - But PRs created via the API or other tooling sometimes bypass the template > - We also require Greptile automated review and passing tests, but this wasn't clearly documented > - This PR updates CONTRIBUTING.md to explicitly require use of the PR template, a 5/5 Greptile score, and passing tests > - The benefit is contributors have clear, upfront expectations for what a mergeable PR looks like ## What Changed - Added a new "PR Requirements (all PRs)" section to CONTRIBUTING.md with three subsections: - **Use the PR Template** — links to `.github/PULL_REQUEST_TEMPLATE.md` and explains it must be used even when creating PRs outside the GitHub UI - **Tests Must Pass** — requires local test runs and green CI - **Greptile Review** — requires 5/5 score with all comments addressed - Updated Path 1 and Path 2 bullet points to reference the PR template, Greptile 5/5, and CI requirements specifically - Updated "Writing a Good PR message" section to link to the PR template and clarify all sections are required ## Verification - Read the updated CONTRIBUTING.md and verify it clearly references the PR template, Greptile 5/5 requirement, and test requirements - Verify all links to `.github/PULL_REQUEST_TEMPLATE.md` resolve correctly ## Risks - Low risk — documentation-only change, no code affected ## Model Used - Provider: Anthropic Claude - Model ID: claude-opus-4-6 (1M context) - Capabilities: tool use, code editing ## 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 run tests locally and they pass - [x] 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] I will address all Greptile and reviewer comments before requesting merge --------- Co-authored-by: Paperclip <noreply@paperclip.ing>
90 lines
4.2 KiB
Markdown
90 lines
4.2 KiB
Markdown
# Contributing Guide
|
|
|
|
Thanks for wanting to contribute!
|
|
|
|
We really appreciate both small fixes and thoughtful larger changes.
|
|
|
|
## Two Paths to Get Your Pull Request Accepted
|
|
|
|
### Path 1: Small, Focused Changes (Fastest way to get merged)
|
|
|
|
- Pick **one** clear thing to fix/improve
|
|
- Touch the **smallest possible number of files**
|
|
- Make sure the change is very targeted and easy to review
|
|
- All tests pass and CI is green
|
|
- Greptile score is 5/5 with all comments addressed
|
|
- Use the [PR template](.github/PULL_REQUEST_TEMPLATE.md)
|
|
|
|
These almost always get merged quickly when they're clean.
|
|
|
|
### Path 2: Bigger or Impactful Changes
|
|
|
|
- **First** talk about it in Discord → #dev channel
|
|
→ Describe what you're trying to solve
|
|
→ Share rough ideas / approach
|
|
- Once there's rough agreement, build it
|
|
- In your PR include:
|
|
- Before / After screenshots (or short video if UI/behavior change)
|
|
- Clear description of what & why
|
|
- Proof it works (manual testing notes)
|
|
- All tests passing and CI green
|
|
- Greptile score 5/5 with all comments addressed
|
|
- [PR template](.github/PULL_REQUEST_TEMPLATE.md) fully filled out
|
|
|
|
PRs that follow this path are **much** more likely to be accepted, even when they're large.
|
|
|
|
## PR Requirements (all PRs)
|
|
|
|
### Use the PR Template
|
|
|
|
Every pull request **must** follow the PR template at [`.github/PULL_REQUEST_TEMPLATE.md`](.github/PULL_REQUEST_TEMPLATE.md). If you create a PR via the GitHub API or other tooling that bypasses the template, copy its contents into your PR description manually. The template includes required sections: Thinking Path, What Changed, Verification, Risks, and a Checklist.
|
|
|
|
### Tests Must Pass
|
|
|
|
All tests must pass before a PR can be merged. Run them locally first and verify CI is green after pushing.
|
|
|
|
### Greptile Review
|
|
|
|
We use [Greptile](https://greptile.com) for automated code review. Your PR must achieve a **5/5 Greptile score** with **all Greptile comments addressed** before it can be merged. If Greptile leaves comments, fix or respond to each one and request a re-review.
|
|
|
|
## General Rules (both paths)
|
|
|
|
- Write clear commit messages
|
|
- Keep PR title + description meaningful
|
|
- One PR = one logical change (unless it's a small related group)
|
|
- Run tests locally first
|
|
- Be kind in discussions 😄
|
|
|
|
## Writing a Good PR message
|
|
|
|
Your PR description must follow the [PR template](.github/PULL_REQUEST_TEMPLATE.md). All sections are required. The "thinking path" at the top explains from the top of the project down to what you fixed. E.g.:
|
|
|
|
### Thinking Path Example 1:
|
|
|
|
> - Paperclip orchestrates ai-agents for zero-human companies
|
|
> - There are many types of adapters for each LLM model provider
|
|
> - But LLM's have a context limit and not all agents can automatically compact their context
|
|
> - So we need to have an adapter-specific configuration for which adapters can and cannot automatically compact their context
|
|
> - This pull request adds per-adapter configuration of compaction, either auto or paperclip managed
|
|
> - That way we can get optimal performance from any adapter/provider in Paperclip
|
|
|
|
### Thinking Path Example 2:
|
|
|
|
> - Paperclip orchestrates ai-agents for zero-human companies
|
|
> - But humans want to watch the agents and oversee their work
|
|
> - Human users also operate in teams and so they need their own logins, profiles, views etc.
|
|
> - So we have a multi-user system for humans
|
|
> - But humans want to be able to update their own profile picture and avatar
|
|
> - But the avatar upload form wasn't saving the avatar to the file storage system
|
|
> - So this PR fixes the avatar upload form to use the file storage service
|
|
> - The benefit is we don't have a one-off file storage for just one aspect of the system, which would cause confusion and extra configuration
|
|
|
|
Then have the rest of your normal PR message after the Thinking Path.
|
|
|
|
This should include details about what you did, why you did it, why it matters & the benefits, how we can verify it works, and any risks.
|
|
|
|
Please include screenshots if possible if you have a visible change. (use something like the [agent-browser skill](https://github.com/vercel-labs/agent-browser/blob/main/skills/agent-browser/SKILL.md) or similar to take screenshots). Ideally, you include before and after screenshots.
|
|
|
|
Questions? Just ask in #dev — we're happy to help.
|
|
|
|
Happy hacking!
|