Contributing

🤝 Contributing

Thanks for considering a contribution to Auris. This page covers the practical mechanics — forking, branching, running checks locally, and opening a pull request. For the technical rulebook the codebase itself follows (naming conventions, validation patterns, how each package is expected to behave), see CLAUDE.md at the repository root; it's the canonical source and this page won't duplicate it.

1. Fork and clone

gh repo fork fuchicar/auris-ai --clone
cd auris-ai

Or without the GitHub CLI: click Fork on fuchicar/auris-ai first, then clone your fork.

git clone https://github.com/<your-username>/auris-ai.git
cd auris-ai
git remote add upstream https://github.com/fuchicar/auris-ai.git

2. Create a branch

main is the stable branch — what go install github.com/fuchicar/auris-ai@latest resolves to — and only takes merges from develop. New work lives in feature branches cut from develop.

git fetch upstream
git checkout -b feat/short-description upstream/develop

Branch names aren't enforced by tooling, but feat/…, fix/…, refactor/…, and docs/… prefixes match the commit convention below and make the diff's intent obvious at a glance.

3. Make your change

A few habits the codebase already follows consistently — matching them keeps your diff easy to review:

• New market driver? Implement every method of market.ProviderAPI, wrap sentinel errors with fmt.Errorf("<driver>: <Method>: %w", market.ErrXxx), add a compile-time var _ market.ProviderAPI = (*Driver)(nil) check, register it in pkg/registry/market.go, and — if any method is a permanent ErrNotSupported regardless of account tier — implement market.CapabilityReporter so the agent doesn't burn a tool-call iteration on something that can never succeed. Full checklist in CLAUDE.md.
• New LLM driver? Same shape: implement llm.AIProvider, wrap sentinel errors, add the compile-time interface check, register in pkg/registry/llm.go. If the provider supports tool calling, Stream must populate ToolCalls/StopReason/Extra on the terminal chunk exactly as Complete does — reuse one mapping helper for both, don't re-derive the parsing twice.
• New Calc* function in pkg/finance? Validate every numeric parameter with the matching helper from pkg/finance/validate.go as the first statements of the function — before any computation. Pick the helper by the parameter's real-world domain (a price is never negative, a return can legitimately be ±1000%+, an annualised rate assumption shouldn't). CLAUDE.md's "Validating numeric tool inputs" section has the full decision table.
• New or removed agent tool? Update the hardcoded count in TestBuildTools_Count (pkg/agent/agent_test.go) to match.
• Integration tests that need live API keys must t.Skip automatically when credentials aren't present — nobody should need a paid API key just to run go test ./....

4. Run the checks locally before opening a PR

go build ./...                  # build everything
go vet ./...                    # static analysis
go test ./... -timeout 120s     # full test suite (hermetic — no network, no keys needed)

These three commands are exactly what CI runs on every push and PR (.github/workflows/ci.yml), so a clean local run means a clean CI run.

5. Commit

The project follows Conventional Commits informally but consistently — recent history looks like:

feat: add currency formatting and selection in portfolio management
fix: preserve assistant text alongside tool calls in OpenAI driver responses
refactor: rename portfolio identifiers for clarity in tests
docs: add Acknowledgements section in both READMEs
chore: expand .gitignore and ignore local AI-agent and personal files
build: drop Windows targets, add FreeBSD amd64 to release matrix

feat: and fix: prefixes aren't just style — GoReleaser's changelog generation (.goreleaser.yaml) groups release notes by exactly these prefixes, so using them correctly makes the auto-generated changelog readable.

6. Open a pull request

PRs target develop, not main. main only takes merges via a deliberate develop→main promotion — see Releasing below.

git push -u origin feat/short-description
gh pr create --base develop --fill

Two automated workflows run on every PR (against either branch):

• ci.yml — go build / go vet / go test ./... -timeout 120s. Must be green.
• claude-code-review.yml — an automated Claude Code review that comments on the diff. Treat its findings the same as a human reviewer's: worth a look, not automatically blocking.

Releasing (promoting develop → main)

When the work accumulated on develop is stable and ready to ship, a maintainer opens a second PR — develop → main. Merging that PR is what gets tagged (e.g. v0.5.0); tagging a main commit then triggers GoReleaser (.github/workflows/release.yml), which is what produces the artefact that go install github.com/fuchicar/auris-ai@latest actually picks up.

# maintainer with push access to both branches
git checkout main && git pull --ff-only upstream main
git merge --no-ff upstream/develop       # keep the promotion as a merge commit on purpose
git tag vX.Y.Z
git push upstream main --follow-tags

Don't open a develop→main PR unless CI is green on develop and nothing half-finished is still in flight — main should always be releasable as-is.

There's no formal CONTRIBUTING.md or code of conduct in the repo yet, so this wiki page is the canonical contribution reference. Keep discussion technical, assume good faith, and prefer a small focused PR over a large mixed one; it's much easier to review and to trace back later.

About AI-assisted contributions

This project has itself been developed with substantial AI coding assistance (see the README's Acknowledgements section) — including an automated @claude-mention workflow (.github/workflows/claude.yml) that can respond to review comments on a PR. AI-assisted PRs are welcome; the same bar applies as to any other contribution: it must build, pass tests, and the human submitting it is responsible for understanding and standing behind the change.