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 or similar to take screenshots). Ideally, you include before and after screenshots.

Questions? Just ask in #dev — we're happy to help.

Happy hacking!

3.2 KiB Raw Blame History