Bug fixes, model provider support, tests, performance work, and documentation merge most readily. Pick something up from help wanted · good first issue · bug · enhancement and claim it in a comment. Use the Bug report or Feature request template for new issues; report security problems through SECURITY.md, never as a public issue. Questions, ideas, and not-yet-actionable proposals belong in Discussions, which reaches the whole team by email.
Project direction, governance, and material product decisions are discussed publicly on dev@maka.apache.org before implementation; implementation-level decisions may live in the pull request.
Every contribution has a human contributor of record who reviews the work, decides to submit it, and owns its accuracy, provenance, and licensing. Agents may commit and push freely; the final review and merge decision always belongs to a human.
Each pull request states whether generative tooling contributed substantively, naming the tool if so; translation, wording edits, autocomplete, and spelling correction don't count. Automated messages must identify themselves. When AI authors a material part of a contribution, add a Generated-by: <tool> trailer to each affected commit, and keep it in the final commit through squash or amend.
Every pull request to main needs an approving review from a committer other than the author and a passing test check; branch protection in .asf.yaml enforces both. An approval stays valid across later pushes — push follow-up commits in the open, and ask for another look when the change grows past what was reviewed. The review must be an independent human judgment — AI review does not count. A maintainer decides whether a change is material and whether the review it received is enough.
Submit only work you have the right to contribute, and record third-party sources, licenses, and attribution. Contributions are licensed under the Apache License 2.0; for material AI-generated content, follow the ASF Generative Tooling Guidance.
Requires Node >=22.19.0 and npm 11.19.0 (root package.json); desktop work needs macOS Apple Silicon.
git clone https://github.com/apache/maka.git
cd maka
npm install # root only — never inside a workspace
npm run build # builds every workspace in dependency order
npm --workspace @maka/core testnpm run dev # desktop app with HMR
npm run cli:dev # TUI; `npm run cli:dev -- run "…"` runs one non-interactive turn
npm test # all workspaces, or: npm --workspace @maka/core testBuilding a single workspace only succeeds when its dependencies are already built — when unsure, build from the root. Tests run against compiled output in dist/; each workspace's test script cleans, builds, then runs node --test. Always go through it.
Before pushing, match CI locally:
npm run lint
npm run format:check
npm run build
npm run typecheck
npx knip --workspace apps/desktop
npx knip --workspace packages/uiArchitecture is documented in ARCHITECTURE.md; evaluation commands and contracts live in packages/eval.
Opening a pull request pre-fills pull_request_template.md; fill it in rather than replacing it.
Branches and titles follow Conventional Commits: branches are <type>/<description>, titles are <type>(<scope>): <summary>. The repository squash-merges, so the title becomes the commit on main; git log shows the types and scopes in use.
For UI changes, include before/after screenshots or a recording. Keep the description short and your own — if it needs many paragraphs, the pull request is probably too large.