139 lines
5.3 KiB
Markdown
139 lines
5.3 KiB
Markdown
# Contributing to Paseo
|
|
|
|
Thank you for taking the time to contribute to Paseo.
|
|
|
|
## Philosophy
|
|
|
|
Paseo is an opinionated product, built on freedom and flexibility: any agent provider, any device, running on your own machine. It is meant to be composable, so you can build the workflow you want. Read more about the product vision [here](docs/product.md).
|
|
|
|
Given Paseo's scope, contributing to to it takes a lot of context that is very hard to transfer. That's why product, design, architecture, and workflow decisions are currently all made by the maintainer.
|
|
|
|
I pick what to build based on whether it fits the product, how many workflows it improves, whether it keeps things composable, whether we can hold the quality bar, and whether I want to build it.
|
|
|
|
## Report bugs in GitHub issues or Discord
|
|
|
|
Open an [issue](https://github.com/getpaseo/paseo/issues) or post in [Discord](https://discord.gg/jz8T2uahpH).
|
|
|
|
> [!IMPORTANT]
|
|
> Feature requests opened as issues will get closed automatically
|
|
|
|
If you used an agent to investigate, paste the raw evidence and repro steps it collected, not its diagnosis.
|
|
|
|
You may submit a PR to fix a bug, please read the PR guidelines below.
|
|
|
|
## Product discussions go in GitHub Discussions or Discord
|
|
|
|
There's no feature request backlog. Open a product discussion in [Discussions](https://github.com/getpaseo/paseo/discussions) or `#product` in [Discord](https://discord.gg/jz8T2uahpH), and frame it as a workflow:
|
|
|
|
- What are you trying to do?
|
|
- How do you do it today?
|
|
- Where does Paseo get in the way?
|
|
- What would the flow look like if it worked for you?
|
|
|
|
"Can you build X" is not useful because it doesn't tell me about your problem.
|
|
|
|
A discussion also lets other people add their own version of the same problem, and that's what I read when I decide what to build.
|
|
|
|
Due to the volume and my limited bandwidth, I may not participate in all the discussions, if something gains interest it will make it's way to me.
|
|
|
|
## Pull requests
|
|
|
|
Anyone can open a pull request, but there are no guarantees of it getting merged, only submit one if you're okay with it being closed.
|
|
|
|
Here is the criteria I use to decide:
|
|
|
|
✅ Likely to be accepted
|
|
|
|
- Fits the product vision
|
|
- One focused change
|
|
- Links the bug it fixes, or the discussion behind it if there is one
|
|
- Addresses bot reviews
|
|
- Explains the problem you're solving
|
|
- QA evidence
|
|
- Automated tests
|
|
- Screenshots or video for UI changes, on every affected platform
|
|
- Says which platforms you tested and which you didn't
|
|
- Maintainer edits enabled
|
|
|
|
⛔️ Will be rejected
|
|
|
|
- Bundles unrelated changes
|
|
- Fails checks
|
|
- Ignores bot reviews
|
|
- Takes a feature or the design in a direction I don't want
|
|
- No QA evidence
|
|
- No tests
|
|
- Clearly fully AI-generated PR
|
|
|
|
### What to expect
|
|
|
|
- PRs that were explicitly approved in a discussion are preferred.
|
|
- Unsolicited PR can be closed without a detailed review.
|
|
- Your PR can be narrowed, refactored, or redesigned.
|
|
- Your PR might be accpeted but not merged immediately.
|
|
- You wil be attributed for your work in the changelog, even if I redesign your PR
|
|
|
|
## QA evidence
|
|
|
|
QA is the main bottleneck of Paseo's product development, and it's not just whether the feature works, it's also whether it meets the quality bar.
|
|
|
|
Pull requests without evidence will be closed.
|
|
|
|
What's accepted:
|
|
|
|
- The shell commands you ran, pasted with their output
|
|
- The tests you added and their results
|
|
- Before and after screenshots
|
|
- A video of the whole interaction
|
|
- Logs, requests, responses
|
|
|
|
Bugs and features both need automated tests, and the tests have to exercise the real thing. UI changes need a video, or a screenshot if it's static.
|
|
|
|
The [QA guide](docs/qa.md) covers what to check for each of these and the tooling to do it.
|
|
|
|
## I want to become a maintainer
|
|
|
|
There's no formal process to become a maintainer, just consistently get involved with the project by answering questions, testing, reproducing bugs, discussing workflows with the community and offer to implement features when we reach an agreement.
|
|
|
|
## FAQ
|
|
|
|
### I'm blocked, where do I go?
|
|
|
|
Join [Discord](https://discord.gg/jz8T2uahpH), ask your questions there.
|
|
|
|
### Do you prefer Github or Discord?
|
|
|
|
I am more active on Discord for general questions.
|
|
|
|
I prefer Github for bugs because the template helps collect information more efficiently.
|
|
|
|
### Why was my feature request closed?
|
|
|
|
Issues are only for bugs. Open it as a product discussion instead, framed as a workflow.
|
|
|
|
### Why didn't my PR get a detailed review?
|
|
|
|
Writing a review is very time consuming and Paseo receives a lot of PRs, I cannot give detailed explanations at volume.
|
|
|
|
### How long until someone looks at my pull request?
|
|
|
|
It depends on what else is going on. QA takes longer than reading the diff. You are welcome to join Discord to ask.
|
|
|
|
### Why do you want tests and a video for a small change?
|
|
|
|
Because it's faster and safer than me checking out and running every PR myself to test it manually.
|
|
|
|
QA evidence help me take your PR seriously for a deeper review and maintainer QA.
|
|
|
|
### I only have one platform, can I still contribute?
|
|
|
|
Yes. Test what you have, and say what you didn't test.
|
|
|
|
### Can I use an agent to write my contribution?
|
|
|
|
Yes, as long as you understand what you're submitting and you tested it yourself.
|
|
|
|
### Is there a roadmap I can read?
|
|
|
|
[docs/product.md](docs/product.md) covers the direction. There's no public list of what I'm building next.
|