Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
123 lines (90 loc) · 3.96 KB

CONTRIBUTING.md

File metadata and controls

123 lines (90 loc) · 3.96 KB
Raw

Contributing to MeshCore-Desktop

Thanks for your interest in contributing. Here's everything you need to get started.

Note for coding agents: AGENTS.md is the canonical instruction set, with domain-specific detail in .agents/skills/. This guide is the human-facing summary and defers to those for conventions.

Prerequisites

  • Node.js 20+
  • npm 10+
  • Chrome or Edge — required for Web Serial (USB) and Web Bluetooth (BLE). The WiFi WebSocket transport works in any modern browser.
  • A MeshCore companion radio (optional but helpful for end-to-end testing)

Development Setup

git clone https://github.com/kNoAPP/MeshCore-Desktop.git
cd MeshCore-Desktop
npm install
npm run dev

Run all checks before pushing — CI enforces every one of them:

npm run spell-check   # cspell
npm run format:check  # Prettier (run `npm run format` to auto-fix)
npm run lint          # ESLint
npm run type-check    # TypeScript
npm run build         # static export → out/

Branch Naming

Branches should follow this pattern:

<handle>/<issue#>-<type>-<short-description>

Examples: kNoAPP/41-feat-wifi-reconnect, mario/none-chore-modify-eslint, docs/readme-update

If there's no linked issue, specify none. Types: feat, fix, docs, refactor, test, ci, chore

Commit Messages

This project uses Conventional Commits:

<type>(<scope>): <short description>

[optional body]

[optional footer]

Examples:

  • feat(transport): add WiFi auto-reconnect on disconnect
  • fix(parser): handle malformed BLE frames gracefully
  • docs: update browser requirements in README

PR titles must also follow this format — CI will reject non-conforming titles.

Pull Request Process

develop is protected: every change lands through a pull request, and nothing is ever committed or pushed to develop directly.

  1. Fork the repo and create your branch from develop (the default branch)
  2. Make your changes with all five checks passing (spell-check, format check, lint, type-check, build)
  3. Fill out the PR template completely — replace each None placeholder if applicable and leave the guidance comments in place
  4. If the change alters the UI in any perceivable way, put before and after screenshots in the Description
  5. Open the PR against develop; @kNoAPP is requested automatically via CODEOWNERS

First-time contributors are welcome to add themselves to the AUTHORS file in the same PR — anyone who has contributed to the project (not just via code) is encouraged to do so.

PRs that change the binary protocol layer (lib/meshcore/) should include a description of which Companion Protocol commands are affected and reference the relevant protocol docs.

Code Style

The full policy lives in the code-style skill (.agents/skills/code-style/). The essentials:

  • TypeScript strict mode — no any, no // @ts-ignore without a comment explaining why
  • All user-facing text is localized with react-i18next — add strings to locales/en.json and render with t('...'); never hardcode display text
  • TSDoc on the public API surface; inline // comments only when the why is non-obvious
  • No new abstractions beyond what the immediate task requires
  • Tailwind classes for layout/spacing; CSS variables (app/globals.css) for theming
  • State changes go through Zustand actions in store/meshStore.ts, not local component state

Adding Words to the Spell Checker

If you introduce a legitimate technical term that cspell flags, add it to the words array in cspell.json.

Reporting Issues