Thanks for helping out! This is a small project with a few firm conventions — following them keeps the history clean and the architecture intact.
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/diff-number-equality
# ...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: add path filters to webhooks,fix: compare numbers by value in the diff. 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 testThe layout is hexagonal — see docs/architecture.md. The two rules that matter when writing code:
- Use-case logic lives in
src/application/only. HTTP handlers and the scheduler are thin translators; if you find yourself orchestrating git-secrets-HTTP work in a handler, move it to an application function. - Validate at load, not at run. Everything a configuration item says that can be
checked without reaching a system is checked when the configuration loads, so a
bad push fails
--check-config, not a run at 3 a.m.
Dependency direction is adapters → application → ports → domain, never the reverse.
domain/ stays pure: std + serde only, plus the types it shares with unified-api from
auth (Credential, LdapConfig).
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.
- Handler in the matching file under
src/adapters/in/http/(one file per resource) - Route in
src/adapters/in/http/routes.rs - Register the handler in
paths(...)— and any response structs incomponents(schemas(...))— insrc/adapters/in/http/openapi.rs, or it won't appear in Swagger - Integration test in
tests/
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 GitHub
Release and the ghcr.io/opusprojects/unified-gitops:X.Y.Z image. Only releases publish
images: latest always means the newest release, never the tip of main —
consumers should still pin the version tag. See
docs/releasing.md.
cargo test # unit + integration; integration tests use the fixtures under tests/No external services are needed to run the full suite: repositories are local file://
ones, and webhooks go to a recorder. See docs/testing.md for what the suite covers, running
a subset, and where new tests belong.