diff --git a/apps/web/CONTRIBUTING.md b/CONTRIBUTING.md similarity index 60% rename from apps/web/CONTRIBUTING.md rename to CONTRIBUTING.md index 64dd2be56..b795ca490 100644 --- a/apps/web/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -18,8 +18,9 @@ Understanding how the packages are organized will make it much easier to contrib [Meshtastic Web](https://github.com/meshtastic/web/) ### Prerequisites -- [Node.js](https://nodejs.org/) (v22 or later) -- [pnpm](https://pnpm.io/) (v10.14.x or later) +- [Node.js](https://nodejs.org/) (v24, the version CI uses) +- [pnpm](https://pnpm.io/) (the version pinned in the root `package.json` `packageManager` field; Corepack picks it up automatically) +- [Buf CLI](https://buf.build/docs/cli/installation/) (only needed to build `@meshtastic/protobufs`, e.g. a full `pnpm -r build`; not needed to run the dev server once the stubs are generated) - Git ### Installation @@ -35,7 +36,7 @@ pnpm install Start the development server: ```bash -pnpm --filter @meshtastic/web dev +pnpm --filter meshtastic-web dev ``` Once running, the site will be available at: @@ -47,10 +48,15 @@ Once running, the site will be available at: Meshtastic Web uses a **monorepo** setup managed with **pnpm workspaces**: ``` +/apps + └─ web # React reference web client /packages - ├─ web # React frontend - ├─ core # Shared types & logic - ├─ transport-* # Transport layer packages + ├─ sdk # Framework-agnostic TypeScript SDK + ├─ sdk-react # React hooks + MeshProvider on top of @meshtastic/sdk + ├─ ui # Shared Radix + Tailwind component library + ├─ sdk-storage-sqlocal # SQLite WASM (OPFS) persistence adapters for the SDK + ├─ protobufs # Generated TypeScript stubs (via buf generate) + ├─ transport-* # Runtime-specific transport packages └─ ...other packages ``` @@ -70,17 +76,25 @@ Meshtastic Web uses a **monorepo** setup managed with **pnpm workspaces**: 2. **Make your changes locally** and verify that the app runs as expected at `http://localhost:3000`. -3. **Commit your changes** with a descriptive commit message that follows the [Conventional Commits](https://www.conventionalcommits.org/) style. +3. **Lint, format and test** before you push. A pre-commit hook (husky + lint-staged) runs oxlint and oxfmt on staged files, but run the full checks yourself too: -4. **Open a Pull Request (PR)** from your fork's branch to the main repository's `main` branch on GitHub: + ```bash + pnpm check # oxlint + oxfmt --check (CI runs this) + pnpm check:fix # auto-fix lint and formatting issues + pnpm test # Vitest + ``` + +4. **Commit your changes** with a descriptive commit message that follows the [Conventional Commits](https://www.conventionalcommits.org/) style. + +5. **Open a Pull Request (PR)** from your fork's branch to the main repository's `main` branch on GitHub: - Clearly describe the problem and solution. - Reference related issues (e.g., `Fixes #123`). - Keep PRs focused on a single feature or fix. - Complete all fields in the PR template. - Tag a **Meshtastic Web developer** in the PR for review. -5. **CI/CD**: - - Our GitHub Actions workflows handle builds, linting, and packaging automatically. +6. **CI/CD**: + - Our GitHub Actions workflows handle builds, linting, formatting, tests, and packaging automatically. - All checks must pass before merge. --- @@ -89,25 +103,33 @@ Meshtastic Web uses a **monorepo** setup managed with **pnpm workspaces**: Meshtastic Web supports multiple languages. If your changes introduce **new user-facing strings**: -- Add them to the **`en.json`** file. +- Add them to the matching namespace file in **`apps/web/public/i18n/locales/en/`** (e.g. `common.json`, `ui.json`). See the namespace rules in the i18n Developer Guide below. - Do **not** hardcode English strings directly in components. - This ensures they can be translated into other languages. 🔗 See these guides for more details: -- [i18n Developer Guide](https://github.com/meshtastic/web/blob/main/packages/web/CONTRIBUTING_I18N_DEVELOPER_GUIDE.md) -- [Translation Contribution Guide](https://github.com/meshtastic/web/blob/main/packages/web/CONTRIBUTING_TRANSLATIONS.md) +- [i18n Developer Guide](./CONTRIBUTING_I18N_DEVELOPER_GUIDE.md) +- [Translation Contribution Guide](./CONTRIBUTING_TRANSLATIONS.md) --- ## 🧪 Testing -Tests are written with [Vitest](https://vitest.dev/). +Unit and component tests are written with [Vitest](https://vitest.dev/). -Run all tests locally with: +Run all tests locally from the repo root with: ```bash -pnpm --filter @meshtastic/web test +pnpm test ``` +To run only the web app's tests: + +```bash +pnpm --filter meshtastic-web test +``` + +End-to-end tests use [Playwright](https://playwright.dev/) against simulated `meshtasticd` nodes (`pnpm test:e2e`) and run in CI. They need extra setup (Docker and Python); see [`e2e/README.md`](./e2e/README.md). + Please include tests for new features and bug fixes whenever possible. --- @@ -147,4 +169,4 @@ Join the conversation: --- ## 📜 License -By contributing, you agree that your contributions will be licensed under the [GPL-3.0-only License](../../LICENSE). +By contributing, you agree that your contributions will be licensed under the [GPL-3.0-only License](./LICENSE). diff --git a/apps/web/CONTRIBUTING_I18N_DEVELOPER_GUIDE.md b/CONTRIBUTING_I18N_DEVELOPER_GUIDE.md similarity index 94% rename from apps/web/CONTRIBUTING_I18N_DEVELOPER_GUIDE.md rename to CONTRIBUTING_I18N_DEVELOPER_GUIDE.md index 4f9e656b0..df4b84c31 100644 --- a/apps/web/CONTRIBUTING_I18N_DEVELOPER_GUIDE.md +++ b/CONTRIBUTING_I18N_DEVELOPER_GUIDE.md @@ -13,7 +13,7 @@ your needs already exists. Many common labels like "Save," "Cancel," "Name," "Description," "Loading...," or "Error" are likely already present, especially in the common.json namespace. Reusing existing keys prevents duplication and ensures consistency across the application. Using your code editor's search -function across the /i18n/locales/en/ directory is an effective way to do this. +function across the apps/web/public/i18n/locales/en/ directory is an effective way to do this. ### Key Naming and Structure Rules @@ -57,7 +57,7 @@ when creating new keys in the JSON files. ### Namespace Rules We use namespaces to organize keys. All source keys are added to the English -(`en`) files located at `/packages/web/public/i18n/locales/en/`. Place your new keys in the +(`en`) files located at `/apps/web/public/i18n/locales/en/`. Place your new keys in the appropriate file based on these rules: - `common.json`: diff --git a/apps/web/CONTRIBUTING_TRANSLATIONS.md b/CONTRIBUTING_TRANSLATIONS.md similarity index 100% rename from apps/web/CONTRIBUTING_TRANSLATIONS.md rename to CONTRIBUTING_TRANSLATIONS.md diff --git a/README.md b/README.md index aae4e0feb..7f95a8350 100644 --- a/README.md +++ b/README.md @@ -140,6 +140,14 @@ pnpm check pnpm check:fix ``` +## Contributing + +See [CONTRIBUTING.md](./CONTRIBUTING.md) for the full workflow, branch and +commit conventions, and i18n guidance. Translations live in the +[Translation Contribution Guide](./CONTRIBUTING_TRANSLATIONS.md); adding +new user-facing strings is covered by the +[i18n Developer Guide](./CONTRIBUTING_I18N_DEVELOPER_GUIDE.md). + ## Developing ### Adding a new feature slice to `@meshtastic/sdk` diff --git a/apps/web/README.md b/apps/web/README.md index 8a5f9d57a..837cf7eb0 100644 --- a/apps/web/README.md +++ b/apps/web/README.md @@ -150,6 +150,6 @@ requests: Meshtastic nodes. Please review our -[Contribution Guidelines](https://github.com/meshtastic/web/blob/main/apps/web/CONTRIBUTING.md) +[Contribution Guidelines](https://github.com/meshtastic/web/blob/main/CONTRIBUTING.md) before submitting a pull request. We appreciate your help in making the project better! diff --git a/e2e/README.md b/e2e/README.md index 47b1fcd1c..44bbbc2dc 100644 --- a/e2e/README.md +++ b/e2e/README.md @@ -36,7 +36,8 @@ in Docker, meshed over the firmware's built-in **UDP multicast** LAN transport ## Running locally (Docker sim — default) -Prerequisites: Docker, Node + pnpm (`11.5.2`), Python 3.11+. +Prerequisites: Docker, Node 24 + pnpm (the version in the root +`package.json` `packageManager` field), Python 3.11+. ```bash pnpm install