For contributors. Covers workflow, testing, CI, and the recipe for adding a new capability.
- Contributing — workflow, PR process, scope rules.
- Conventional Commits — types, scopes, examples.
- Adding a capability — the 6-file recipe for a new feature.
- Testing —
make test,make cover, harness patterns. - CI — workflows and what each job does.
- Releasing — release-please + GoReleaser + tap flow.
- Roadmap — planned features and explicit non-goals.
git clone https://github.com/amiwrpremium/macontrol.git
cd macontrol
make lint test # check before committing
git switch -c feat/my-thing
# … make changes …
git commit -am "feat(scope): one-line summary"
git push -u origin feat/my-thing
gh pr create| Type | Example | Where it goes |
|---|---|---|
| Bug fix in domain layer | wifi parser misses an SSID format | internal/domain/<pkg>/ + test |
| New button on existing category | bt:rename to rename a paired device |
keyboard + handler + (maybe) flow + test |
| New category | 🎵 Music for /music controls |
full 6-file recipe |
| New CLI subcommand | macontrol export-config |
cmd/macontrol/<file>.go |
| Docs improvement | typo, clarification | edit docs/**/*.md |
| Build/CI tweak | new lint rule, new workflow | .github/, .golangci.yml, etc. |
The rule of thumb: small, focused PRs land faster. A 50-line PR that does one thing is easier to review than a 500-line PR that does five.
- Contributing — read first.
- Conventional Commits — required for PR titles.
- Architecture → Project layout — find your way around.
- Architecture → Design decisions — understand the constraints before proposing changes.
For specific feature work:
- Adding a button → Adding a capability.
- Adding tests → Testing.
- Fixing CI → CI.
- Cutting a release → Releasing.