| # 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 automated checks pass (including Greptile comments) |
| - No new lint/test failures |
|
|
| 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 |
| - All Greptile + other PR comments addressed |
|
|
| PRs that follow this path are **much** more likely to be accepted, even when they're large. |
|
|
| ## 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 |
|
|
| Please include a "thinking path" at the top of your PR message that 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! |
|
|
