3.0 KiB
Contributing to herdr
Thanks for wanting to contribute.
Herdr came from my own need for a fast, simple, effective workspace manager for coding agents. I care a lot about how it looks, feels, and works, so many design and technical decisions here are deliberate.
This guide exists so I can keep herdr manageable as a solo project and keep it from drifting from what it is supposed to be.
The One Rule
You must understand your code. If you cannot explain what your changes do, how they behave at the edges, and how they fit herdr's existing design, your PR will be closed.
Using AI to write code is fine. Submitting code you do not understand is not.
Herdr is opinionated
Herdr has a specific direction for how it should look, feel, and work.
That includes interaction patterns, layout behavior, mouse ergonomics, terminology, and how features fit the product as a whole.
If your idea changes or contradicts that direction, do not start with a PR. Start with an issue.
If you have a suggestion, disagreement, or contradiction with the current product direction, that belongs in an issue first.
First-time contributors
We use an approval gate for new contributors.
Before opening your first PR, open an issue describing what you want to change and why. Keep it short. Write in your own voice. If you intend to implement it yourself, add the intends-to-pr label. A maintainer will comment /approve if the direction is approved. Once approved, you can open PRs.
This exists because AI makes it trivial to generate plausible-looking contributions that do not fit the app.
What to put in a first issue
Your first issue should answer these questions clearly:
- what is the current behavior
- what do you want to change
- why this change belongs in herdr
- whether this changes UI, interaction, or workflow expectations
- whether you intend to implement it yourself
If your proposal changes the visual language, interaction model, or overall product direction, say that directly. That is exactly what issues are for.
If your issue does not make the direction clear, it will likely be closed.
If you plan to implement the change yourself, say that directly in the issue and use the intends-to-pr label. That signals intent. It is not approval.
Before submitting a PR
Install the repo hook once in your clone.
just install-hooks
The pre-commit hook runs cargo fmt --check before every commit.
Run the PR checks and make sure they pass.
just ci
just ci runs cargo fmt --check and cargo nextest run.
Do not open a PR that bypasses failing tests, formatting, or build errors.
PR scope
Small bug fixes that clearly match the existing design are good candidates for PRs after approval.
Bigger changes to UI, behavior, interaction patterns, persistence, or architecture need issue discussion first.
If a PR introduces a feature without prior alignment, or changes herdr's feel without discussion, it will likely be closed.
Questions?
Open an issue first.
clank'd from pi