Contributing to Homer
Getting started
- Backend (Kotlin/Ktor): see
app/CLAUDE.mdfor architecture and conventions. Requires JDK 25. - Console (Next.js): see
console/CLAUDE.mdfor architecture and conventions. Requires Node. - Questions and help go to GitHub Discussions.
- Looking for something to pick up? See the good first issues and help wanted issues, then follow Submitting changes. Issues aren't assigned or reserved, so there's no need to ask first: open a pull request when you're ready. The first one that closes the issue and passes review is merged.
Before submitting
Run the relevant verification command and make sure it's green:
| Area touched | Verify |
|---|---|
app/** | JAVA_HOME=<path to a JDK 25> app/gradlew -p app ktlintFormat :app:test :app:checkThirdPartyNotices |
app/buildSrc/** | JAVA_HOME=<path to a JDK 25> app/gradlew -p app/buildSrc check (a separate build — -p app check does not cover it) |
console/** | cd console && npm run lint && npm test && npm run build && npm run licenses:check |
clients/python/** | cd clients/python && .venv/bin/python -m pytest (venv setup: clients/python/homer_langgraph/CLAUDE.md) |
tools/quality/** | cd tools/quality && npm ci && npm test |
site/**, or a file the site publishes (listed in site/scripts/sources.mjs, every ADR) | cd site && npm ci && npm test && npm run docs:build (fails on a link to a missing file) |
app/schemas/** or Agent.kt / AppConfig.kt | backend verify (runs SchemaValidationTest, AgentMdExamplesTest) |
.github/ISSUE_TEMPLATE/** or .github/pull_request_template.md | JAVA_HOME=<path to a JDK 25> app/gradlew -p app :app:test --tests 'homer.app.CommunityTemplatesTest' (the community-template guard; node tools/quality/changed.mjs selects no check for a template-only change) |
Expectations
- Tests are required for new code — see each dev guide's testing section for the stack and layout.
- Every pull request runs the quality checks listed in
docs/quality-checks.md;requiredones fail the CI run.node tools/quality/changed.mjsruns them locally against your change sinceorigin/main(uncommitted edits included), with only the related tests. - One logical change per commit; imperative subject, body explains why.
- User-visible changes get a
CHANGELOG.mdentry under[Unreleased]. - Architectural decisions with lasting impact get an ADR under
docs/adr/— seedocs/adr/README.md.
Submitting changes
Open a pull request on github.com/livesport/homer.
- Open an issue first. A maintainer or triager labels it
acceptedonce the change belongs in Homer and is welcome there; only those roles can set labels. - Link the accepted issue from the pull request:
Closes #123in the description, or the pull request's Development field. ThePR policycheck fails a pull request that links no accepted issue of this repository. Labelling the issue does not re-run the check, so re-run it afterwards. ADR-0090 records why the gate works this way. - CI runs on GitHub-hosted runners. A first-time contributor's first run waits until a maintainer approves it, as GitHub does by default.
- Reviews start once every automated check is green. A pull request from a member of the
livesportorganization, or from Homer's own factory, gets the AI review and a maintainer's review. One from anyone else gets a maintainer's review first, and the AI review only after the maintainer approves, so no automated review runs on code nobody has read. A new push dismisses the approval. - A pull request merges once every check, the AI review and a maintainer's approval are green on its latest commit and every review conversation is resolved. The AI review can block a merge but never approves one. Only maintainers merge.