Contributing

Issues, ideas, pull requests, commit conventions, tests, and how AI-assisted work is credited.

Contributions are welcome: bug reports, ideas, documentation fixes, tests, and code. This page is the process. The Development Guide covers the repository layout and how to build and test each component.

Report a bug or request a feature

  • Not sure it is a bug, or have a question? Open a Discussion.
  • Found a defect? Open an issue on the repo where you found it, using the bug report template. If the Quickstart itself failed, use the quickstart-failed template; it asks for what is needed to reproduce a fresh-cluster run.
  • Have an idea for a feature? Start in Discussions, so the shape of the idea can settle before anyone writes code. A maintainer turns it into an issue when the work is clear. The feature request template works too when you already know what you want.
  • Larger or cross-cutting change? Open an issue titled Proposal: <summary> describing the problem, the approach, the alternatives, and what it touches (CRDs, runtime, dashboard, crews). See Governance.

Open a pull request

  1. Fork the repository you want to change, clone your fork, and branch off main.

  2. Make the change, with tests (see below).

  3. Run the test suite for the component you touched. For the kubemoot repo, run the quickstart against a local kind cluster as a smoke test; it installs the operator, Ollama serving a small CPU model from the cluster’s model catalog, and a two-agent crew, asks the crew a question, and checks that an answer comes back:

    kind create cluster --name kubemoot
    ./quickstart/quickstart.sh
    

    The script installs the chart of the release your checkout belongs to. On a branch that changed the quickstart files it stops and says so; to test your own images or chart, set KUBEMOOT_CHART and KUBEMOOT_IMAGE_TAG as the quickstart README describes.

  4. Commit with a conventional-commit message (below).

  5. Open a pull request against main using the template, and say what changed and why.

Once merged, a pull request builds a release candidate from main and ships in the next published release; see Releases. Install final releases, not main.

Small, focused pull requests review faster: one concern per pull request. A maintainer review and approval is required to merge. The Governance page describes how public pull requests are handled.

Commit messages

Versions come from git tags, and the release pipeline computes each version from the conventional-commit prefixes since the previous release. Never type a version number by hand. Use a Conventional Commits prefix:

PrefixVersion bump
fix:patch
feat:minor
docs:, chore:, refactor:patch
feat!:, fix!:, or a footer containing BREAKING CHANGEmajor

See Releases for what a bump does.

Tests ship with the code

A pull request that adds a function, method, or class includes a test for it, covering the expected input and at least one unexpected one. New functionality comes with tests in the component’s automated test suite, and a bug fix comes with a test that fails without the fix. Tests are part of the change, not a follow-up. CI runs these automated suites; the Development Guide lists the command for each component (make test, go test ./..., ./gradlew test, npm test).

Keep functions at a cyclomatic complexity of 10 or less. Past that, extract methods, use a dispatch table, or decompose the conditional before opening the pull request.

Linters and warnings

Run the linter of the component you touched before you open a pull request; the Development Guide lists the commands. What runs automatically:

CheckWhere it runs
golangci-lint (with the repository’s .golangci.yml) and a go mod tidy checkEvery Go module in kubemoot and kmctl, on every pull request
CheckstyleThe Java services in kubemoot (agent runtime, MCP gateway, indexer)
tsc, ESLint, and svelte-checkCrewForge on every pull request; the dashboard in its image build
ruffThe Python code in kubemoot and crews
ShellCheckThe release scripts in kubemoot, crews, kmctl, and vscode-crewforge
CodeQLEvery repository, on every pull request, every push to main, and weekly
SonarQube quality gateEvery push to main in kubemoot, kmctl, vscode-crewforge, and crews

Each of these blocks the build on any finding, and every repository is at zero.

Fix every warning these tools report. When a finding is a false positive, suppress it on that line with a comment that gives the reason (//nolint:<linter> // why in Go, // NOSONAR <rule>: why in Java, // eslint-disable-next-line <rule> -- why in TypeScript); do not turn a rule off for the whole repository. A failing check means the code needs to change, not the check.

Conventions a reviewer looks for

  • Prompts in ADL. Agent prompt text lives in PromptModule resources written in ADL (the Architecture Definition Language), never inline in an Agent spec. See Write Agents & ADL.
  • Lifecycle belongs to the operator. Cleanup, garbage collection, and namespace management are handled in the operator with finalizers and owner references, not in client-side tools.
  • Documentation with the change. Component docs live in that component’s docs/ directory; the site shell and cross-cutting chapters live in the kubemoot-docs repo.

AI-assisted working style

Kubemoot is built largely by AI coding agents working under maintainer direction. Their work is held to the same gates as anyone else’s: tests, complexity limits, and review. The code is judged on what it does, not on who or what typed it, and contributions from AI assistants are welcome on the same terms.

Agent-authored commits are identifiable:

  • The author is Klaude <klaude@kubemoot.org>, the identity the project’s agents commit under.
  • The model that did the work is credited in a Co-Authored-By: trailer on the commit.

If an AI assistant helped with your contribution, you are welcome to note it in the pull request; it is not required.

Credit

A contribution the maintainers rework to fit the project’s design is still credited to you. A significant contribution, such as an architectural change or a notable feature, is credited with a Co-authored-by trailer on the commit. Smaller ideas are acknowledged in the issue or pull request discussion.

Licensing and sign-off

Kubemoot repositories are licensed under the Apache License 2.0. By submitting a contribution you agree it is licensed under the same terms as the repository you are contributing to. There is no contributor license agreement (CLA).

Every commit in a pull request requires a Developer Certificate of Origin (DCO) sign-off, which certifies that you have the right to submit the change. Read the certificate at developercertificate.org. Add the sign-off with git commit -s, which appends a Signed-off-by: Name <email> line matching the commit author. A pull request check named “DCO” verifies the sign-off.

To fix a missing sign-off:

git commit --amend -s --no-edit      # the last commit
git rebase --signoff <base-branch>   # several commits

Then force-push the pull request branch.

Response time

The project has a single maintainer today, so responses to issues and pull requests are best effort, with no guaranteed window. If a pull request sits without review, a polite ping after a week or two is fine.