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.
To self-assign an unclaimed issue, post a comment whose entire body is exactly take; post untake to remove your assignment. Other claim text does not trigger the workflow.
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). Direct Peer or Peer Mesh Desktop development additionally needs Rust stable 1.98 or newer and Xcode Command Line Tools on macOS, or MSVC Build Tools on Windows.
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 run test:distnpm 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 run test:distBuilding a single workspace only succeeds when its dependencies are already built — when unsure, build from the root. Tests run against compiled output in dist/, so test:dist covers whatever the last build produced; rebuild before running it. npm test from the root does both.
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.