> ## Documentation Index > Fetch the complete documentation index at: https://docs.mira-app.dev/llms.txt > Use this file to discover all available pages before exploring further. # Contributing > Everything you need to go from zero to your first merged PR on MIRA. MIRA is open-source under the MIT licence. This page is your **Day Zero** guide — it covers everything from cloning the repo to getting a pull request merged, including how branches, commits, releases, and CI all fit together. Read this once, end to end, before writing any code. *** ## 1. Prerequisites Before anything else, make sure you have the following installed: | Tool | Required version | How to install | | ------- | ---------------- | -------------------------------------------------------------- | | Git | any | [git-scm.com](https://git-scm.com) | | Node.js | 22 LTS | [nodejs.org](https://nodejs.org) or `nvm install 22` | | npm | ≥ 10 | Bundled with Node.js 22 | | Python | 3.11 | [python.org](https://python.org) or `brew install python@3.11` | Node.js 22 LTS is required. If you use nvm, run `nvm install 22 && nvm use 22` before anything else. *** ## 2. Fork and clone You work on your own fork — you never push directly to `satyendra2013/mira-app`. Go to [github.com/satyendra2013/mira-app](https://github.com/satyendra2013/mira-app) and click **Fork** → **Create fork**. ```bash theme={null} git clone https://github.com//mira-app.git cd mira-app ``` ```bash theme={null} git remote add upstream https://github.com/satyendra2013/mira-app.git git fetch upstream ``` You now have two remotes: `origin` (your fork) and `upstream` (the canonical repo). You pull from `upstream`, push to `origin`. *** ## 3. Set up the dev environment ```bash theme={null} # Install all Node.js dependencies (also activates husky git hooks automatically) npm install # Create a Python virtual environment for the engines python3.11 -m venv .venv source .venv/bin/activate # macOS / Linux # .venv\Scripts\activate # Windows # Install Python dependencies pip install -r resources/requirements.txt ``` That's it. The `npm install` step also runs `husky` which installs the git hooks — including the commit message linter. You don't need to set anything up manually. Verify your environment: ```bash theme={null} npm run typecheck # should exit 0 npm run lint # should exit 0 npm test # runs the Jest suite ``` *** ## 4. Branch naming Every piece of work lives on its own branch. Branch from `main` and use the following prefixes so the purpose is immediately clear: | Prefix | Use for | | ----------- | ------------------------------------------ | | `feat/` | A new feature | | `fix/` | A bug fix | | `docs/` | Documentation only | | `perf/` | Performance improvement | | `refactor/` | Internal refactor with no behaviour change | | `chore/` | Tooling, dependency updates, CI | | `test/` | Adding or fixing tests only | ```bash theme={null} # Always start from an up-to-date main git checkout main git pull upstream main # Create your branch git checkout -b feat/repl-colour-theme # or git checkout -b fix/nae-token-overflow ``` Keep branch names lowercase, hyphen-separated, and specific. `fix/crash` is bad. `fix/nae-crash-on-empty-document` is good. *** ## 5. Conventional Commits — the only commit format accepted MIRA uses [Conventional Commits](https://www.conventionalcommits.org). Every commit message is validated by a git hook the moment you run `git commit`. A badly formatted commit is **rejected immediately** — you fix it before it's recorded. ### Format ``` (): [optional body — explain WHY, not what] [optional footer — e.g. Closes #123] ``` The short description must: * be lowercase * not end with a period * be 72 characters or fewer ### Types | Type | When to use | Appears in changelog | Version bump | | ---------- | ------------------------------------ | -------------------- | ------------ | | `feat` | Adding new functionality | ✨ Features | MINOR | | `fix` | Fixing a bug | 🐛 Bug Fixes | PATCH | | `perf` | Measurable performance improvement | ⚡ Performance | PATCH | | `docs` | Documentation only | 📚 Documentation | none | | `refactor` | Code change with no behaviour change | (skipped) | none | | `test` | Adding or fixing tests | (skipped) | none | | `chore` | Build tooling, CI, dependencies | (skipped) | none | | `ci` | CI workflow changes | (skipped) | none | For a **breaking change** (one that changes the IPC contract, DB schema, or engine API), append `!` to the type or add a `BREAKING CHANGE:` footer: ```bash theme={null} git commit -m "feat!: redesign IPC session contract" # or git commit -m "feat(ipc): new session payload shape BREAKING CHANGE: session objects now include engineMode field. Existing integrations must be updated." ``` ### Scope (optional but encouraged) The scope narrows what was changed. Use the name of the module, component, or area: ``` feat(repl): add colour-coded stderr stream fix(nae): handle token budget overflow gracefully docs(skills): clarify custom skill temperature field chore(deps): upgrade electron to 28.4.0 test(rlm): add multi-hop reasoning test case ``` ### Real examples ```bash theme={null} # Accepted ✅ git commit -m "fix(repl): prevent scroll-lock when console is cleared" git commit -m "feat(workflows): add human_review step confirmation modal" git commit -m "docs(mcp): add SSE server setup example" git commit -m "chore(deps): bump better-sqlite3 to 11.11.0" # Rejected ❌ git commit -m "Fixed stuff" # no type git commit -m "feat: Fix the bug." # wrong case + period git commit -m "WIP" # no type ``` *** ## 6. Development workflow ```bash theme={null} # Start the app in development mode (hot reload for renderer) npm run dev ``` The window opens automatically. Changes to the React renderer hot-reload instantly. Changes to the main process require quitting and re-running `npm run dev`. ### Useful commands ```bash theme={null} npm run typecheck # TypeScript type check (no emit) npm run lint # ESLint npm run lint:fix # ESLint with auto-fix npm test # Jest test suite npm run test:watch # Jest in watch mode npm run test:coverage # Jest with coverage report ``` See [Build & Run (Development)](../developer-guide/build-dev) for debugging the main process and Python engines. *** ## 7. Before opening a PR Run this sequence and make sure everything passes: ```bash theme={null} npm run typecheck npm run lint npm test ``` If you changed anything user-facing (UI, settings, engine behaviour), update the relevant `.mdx` file in `docs/`. Documentation PRs are reviewed as carefully as code PRs. *** ## 8. Opening a pull request ```bash theme={null} git push origin feat/repl-colour-theme ``` Go to [github.com/satyendra2013/mira-app](https://github.com/satyendra2013/mira-app). GitHub will show a banner — click **Compare & pull request**. Target branch: `main`. Base repo: `satyendra2013/mira-app`. Never target a release or hotfix branch unless specifically asked. The template will be pre-filled. Complete every section: * **Summary** — one line describing what this PR does * **Type of change** — tick the relevant box * **What changed and why** — explain the reasoning, link to the issue if one exists * **Testing** — which platforms did you verify on? * **Checklist** — all boxes must be checked before requesting review Three checks run on every PR: * **Lint · Typecheck · Test** — must be green * **Commit message format** — validates every commit in the PR against the conventional commits standard If any check fails, fix it before requesting review. Push new commits to the same branch — the PR updates automatically. Don't force-push unless the reviewer specifically asks you to squash. Reply to each review comment individually so the reviewer knows what was addressed. The maintainer squash-merges approved PRs. Your entire branch becomes one clean commit on `main`. Delete your branch after merge. *** ## 9. Keeping your fork in sync Before starting any new piece of work, sync your fork with upstream: ```bash theme={null} git checkout main git fetch upstream git merge upstream/main git push origin main ``` If you have an in-progress branch that needs upstream changes: ```bash theme={null} git checkout feat/my-feature git fetch upstream git rebase upstream/main # resolve any conflicts, then: git push origin feat/my-feature --force-with-lease ``` Use `--force-with-lease` (not `--force`) — it's a safety check that prevents overwriting someone else's push. *** ## 10. Releases (maintainer only) Releases are cut by the maintainer from the `main` branch using `release-it`. Contributors do not cut releases — this section is here so you understand what happens after your PR merges. See [Release Process](../developer-guide/release-process) for the full reference. The short version: ```bash theme={null} # Cut the next beta npm run release:beta # e.g. 0.1.0-beta.1 → 0.1.0-beta.2 # Cut a release candidate npm run release:rc # e.g. 1.0.0-rc.1 # Cut a stable release npm run release # e.g. 1.0.0 ``` `release-it` bumps the version in `package.json`, prepends a `CHANGELOG.md` entry from your commit history, creates a git tag, and opens a GitHub Release — all in one command. *** ## 11. Hotfix branches A hotfix is an urgent fix applied directly to a released version, not via the normal `main` flow. ```bash theme={null} # Branch from the tag you need to fix git checkout -b fix/crash-on-empty-doc v0.1.0-beta.1 # Apply your fix with a conventional commit git commit -m "fix(parser): handle empty document upload gracefully" # Merge back to main git checkout main git merge fix/crash-on-empty-doc # The maintainer then cuts a patch release npm run release ``` *** ## Quick reference card ``` Clone git clone + git remote add upstream Branch git checkout -b fix/description Commit format fix(scope): short description Sync fork git fetch upstream && git merge upstream/main Push PR git push origin your-branch → open PR on GitHub CI checks lint + typecheck + test + commitlint Merge style squash merge by maintainer Release npm run release:beta / release:rc / release ``` *** Set up your local dev environment How versions are cut and published How Electron, React, and the Python engines fit together Community standards Edit this page — [Open a pull request](https://github.com/satyendra2013/mira-app/edit/main/docs/community/contributing.mdx)