Skip to content

Contributing

This is a solo, personal project — but if an agent (or future-you) is touching it, follow the same rules the tooling enforces. These rules live in AGENTS.md and are summarized here.

Branch policy (mandatory)

  • Never commit directly to main.

  • Every change gets its own branch:

    • feature/<slug> — new capability
    • fix/<slug> — bug fix
    • chore/<slug> — tooling, docs, CI

  • Commit on the branch, push it, and open a pull request.

  • Merge to main only when the branch's CI is fully green.

The verification sweep

Before pushing any branch, run the full sweep locally and confirm every step passes:

export JAVA_HOME="$HOME/.jdks/temurin-17"
./gradlew ktlintCheck detekt lint testDebugUnitTest assembleDebug

CI runs the same sweep on every PR/push. Never leave a red build behind — fix locally, push again.

Changelog discipline

Every PR that lands user-visible or structural changes must update CHANGELOG.md under the ## [Unreleased] heading, describing exactly what was added/fixed/changed. The [Unreleased] section is a project invariant: keep it, keep it honest, and trim it only when a release is cut.

Style & sanity

  • Run ./gradlew ktlintFormat and let the formatter decide — don't hand-format.
  • Dependency/plugin versions live only in gradle/libs.versions.toml.
  • Keep pure logic in inject/, settings/, and other non-framework code, and cover it with JVM unit tests.
  • Don't hand-edit generated files (build/, lint-baseline.xml, detekt-baseline.xml, local.properties, signing files).
  • Don't commit secrets, signing keys or local.properties.
  • Load the relevant skill before touching those areas: skills/ad-engine/, skills/theming/, skills/webview-security/, skills/optimization/.