Thanks for helping out! This is a small project with a few firm conventions — following them keeps the history clean and the services that use it safe.
main moves only through squash-merged pull requests, one logical change per PR —
a fix, a dependency bump, a doc edit each get their own. This keeps every change
independently reviewable, bisectable, and revertable.
git checkout main && git pull
git checkout -b <type>/<short-name> # e.g. fix/fetch-after-force-push
# ...make exactly one change, test it...
git commit -am "Short imperative title"
git push -u origin <type>/<short-name>
gh pr create --base mainCommit and PR titles follow Conventional Commits: release-please reads them to pick the next version and to write the CHANGELOG.
- Title:
<type>: short imperative summary, lowercase after the colon —feat: list the tags a pull brought,fix: keep the checkout when a fetch is refused. Types in use:feat,fix,perf,refactor,docs,test,build,chore. - A breaking change adds
!after the type (feat!: ...) or aBREAKING CHANGE:footer in the body. - The squashed title is the CHANGELOG line and decides the next version, so write it for someone reading the release notes: what changes for them. See docs/releasing.md.
- Body (when the change needs explaining): plain prose, what and why, wrapped at ~72 columns. The problem first, then the change.
Every PR must pass, in this order (run them locally before pushing):
cargo fmt --check
cargo clippy --all-targets -- -D warnings
cargo testThis crate is a library services build on; four rules keep it that way:
- Nothing service-specific. What a project item looks like, where its credentials are
stored and how often it is pulled stay in the service. Git sees a
Remote(address and branch) and a map of resolved credential fields. - No secret on a command line. Credentials travel in environment variables; anything git
prints is passed through
redact_userinfobefore it leaves as an error. - What comes from outside is checked before git sees it. A revision is a commit id (hex, four to sixty-four characters), never an option or a ref expression.
- A change here is a change in every service that pins it. Before merging, build them against your branch (see docs/development.md).
The codebase carries teaching comments that explain Rust concepts to the maintainers. They are intentional — do not strip them when refactoring; move them with the code they explain. When you add a non-obvious Rust construct, a comment in the same spirit is welcome. Beyond those, comment only when the why is non-obvious.
Releases are cut by release-please; no one bumps a version, edits the CHANGELOG
or pushes a tag by hand. Every merge into main updates one open
chore: release vX.Y.Z pull request, and merging it creates the tag the
services pin and the GitHub Release. See docs/releasing.md.
cargo test # needs git and tar on PATH; no networkThe tests create real repositories in temporary directories and use them over file://, so they
run the same git commands a service does, without a network. Every line of the crate runs in a
test, and CI keeps it that way: see docs/development.md.