From 1ae8805deff4dc2f2551eaaec55e963842f297de Mon Sep 17 00:00:00 2001 From: Dan Ditomaso Date: Sat, 22 Aug 2026 21:00:01 -0400 Subject: [PATCH 1/4] docs: move contributing guides to repo root Move CONTRIBUTING.md, CONTRIBUTING_I18N_DEVELOPER_GUIDE.md, and CONTRIBUTING_TRANSLATIONS.md from apps/web to the repo root so they are discoverable at the standard location GitHub surfaces (Contributing tab, new-PR sidebar) and apply to the whole monorepo, not just apps/web. While in there, fix stale references in the moved files: - `pnpm --filter @meshtastic/web ...` filters resolve to the root workspace package, not the app; use `meshtastic-web`. - Repo structure block described the pre-monorepo `/packages/web` layout; updated to the current `/apps` + `/packages` split. - i18n guide links used absolute GitHub URLs into `packages/web/`; use relative links now that the files sit next to each other. - i18n developer guide referenced `/packages/web/public/i18n/...`; the path is now `/apps/web/public/i18n/...`. - LICENSE link is now `./LICENSE` (was `../../LICENSE`). Root README gains a Contributing section pointing at the moved files; apps/web README's contributing link updated to the root path. --- apps/web/CONTRIBUTING.md => CONTRIBUTING.md | 20 +++++++++++-------- ...md => CONTRIBUTING_I18N_DEVELOPER_GUIDE.md | 2 +- ...LATIONS.md => CONTRIBUTING_TRANSLATIONS.md | 0 README.md | 8 ++++++++ apps/web/README.md | 2 +- 5 files changed, 22 insertions(+), 10 deletions(-) rename apps/web/CONTRIBUTING.md => CONTRIBUTING.md (86%) rename apps/web/CONTRIBUTING_I18N_DEVELOPER_GUIDE.md => CONTRIBUTING_I18N_DEVELOPER_GUIDE.md (97%) rename apps/web/CONTRIBUTING_TRANSLATIONS.md => CONTRIBUTING_TRANSLATIONS.md (100%) diff --git a/apps/web/CONTRIBUTING.md b/CONTRIBUTING.md similarity index 86% rename from apps/web/CONTRIBUTING.md rename to CONTRIBUTING.md index 64dd2be56..b1a98311b 100644 --- a/apps/web/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -35,7 +35,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 +47,14 @@ 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 + ├─ protobufs # Generated TypeScript stubs (via buf generate) + ├─ transport-* # Runtime-specific transport packages └─ ...other packages ``` @@ -94,8 +98,8 @@ Meshtastic Web supports multiple languages. If your changes introduce **new user - 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) --- @@ -105,7 +109,7 @@ Tests are written with [Vitest](https://vitest.dev/). Run all tests locally with: ```bash -pnpm --filter @meshtastic/web test +pnpm --filter meshtastic-web test ``` Please include tests for new features and bug fixes whenever possible. @@ -147,4 +151,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 97% rename from apps/web/CONTRIBUTING_I18N_DEVELOPER_GUIDE.md rename to CONTRIBUTING_I18N_DEVELOPER_GUIDE.md index 4f9e656b0..9bf9d6104 100644 --- a/apps/web/CONTRIBUTING_I18N_DEVELOPER_GUIDE.md +++ b/CONTRIBUTING_I18N_DEVELOPER_GUIDE.md @@ -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 577e7efaa..2c3de5051 100644 --- a/README.md +++ b/README.md @@ -119,6 +119,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 ccce1876d..1afa7939b 100644 --- a/apps/web/README.md +++ b/apps/web/README.md @@ -151,6 +151,6 @@ requests: Meshtastic nodes. Please review our -[Contribution Guidelines](https://github.com/meshtastic/web/blob/main/packages/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! From 11b793c498f412977959aa2909a2e0daba2648a4 Mon Sep 17 00:00:00 2001 From: Dan Ditomaso Date: Sat, 17 Oct 2026 12:02:02 -0400 Subject: [PATCH 2/4] docs: fix stale packages/web setup path in apps/web README --- apps/web/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/apps/web/README.md b/apps/web/README.md index 1afa7939b..6b73a11a6 100644 --- a/apps/web/README.md +++ b/apps/web/README.md @@ -89,7 +89,7 @@ instructions listed on the home page. Install the dependencies. ```bash -cd packages/web && +cd apps/web && pnpm install ``` From 76fa8657d6e06d23bb2d561c9aeb11519a0273e5 Mon Sep 17 00:00:00 2001 From: Dan Ditomaso Date: Sun, 18 Oct 2026 15:46:21 -0400 Subject: [PATCH 3/4] docs: refresh contributing guide prerequisites, checks and i18n paths - Prerequisites: Node 24 (matches CI), pnpm via packageManager, Buf CLI - Add lint/format/test step (pnpm check, husky pre-commit) to the workflow - Tests: root `pnpm test`, plus a pointer to the Playwright e2e suite - i18n: point at namespaced files under apps/web/public/i18n/locales/en/ - Repo structure: add sdk-storage-sqlocal - Fix remaining locale path in the i18n developer guide - apps/web README: restore repo-root install and `--filter meshtastic-web` commands, keeping the updated contributing link --- CONTRIBUTING.md | 38 ++++++++++++++++++++-------- CONTRIBUTING_I18N_DEVELOPER_GUIDE.md | 2 +- apps/web/README.md | 11 ++++---- 3 files changed, 34 insertions(+), 17 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index b1a98311b..b795ca490 100644 --- a/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 @@ -53,6 +54,7 @@ Meshtastic Web uses a **monorepo** setup managed with **pnpm workspaces**: ├─ 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 @@ -74,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. --- @@ -93,7 +103,7 @@ 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. @@ -104,14 +114,22 @@ Meshtastic Web supports multiple languages. If your changes introduce **new user --- ## 🧪 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. --- diff --git a/CONTRIBUTING_I18N_DEVELOPER_GUIDE.md b/CONTRIBUTING_I18N_DEVELOPER_GUIDE.md index 9bf9d6104..df4b84c31 100644 --- a/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 diff --git a/apps/web/README.md b/apps/web/README.md index 6b73a11a6..837cf7eb0 100644 --- a/apps/web/README.md +++ b/apps/web/README.md @@ -86,17 +86,16 @@ instructions listed on the home page. ### Development -Install the dependencies. +Install the dependencies from the repo root (pnpm workspaces installs every package in one pass). ```bash -cd apps/web && pnpm install ``` -Start the development server: +Start the development server for the web client: ```bash -pnpm run dev +pnpm --filter meshtastic-web dev ``` ### Building and Packaging @@ -104,13 +103,13 @@ pnpm run dev Build the project: ```bash -pnpm run build +pnpm --filter meshtastic-web build ``` GZip the output: ```bash -pnpm run package +pnpm --filter meshtastic-web run package ``` ### Why pnpm? From 893f96500d343d15e5e18653e582bac9d4f6e505 Mon Sep 17 00:00:00 2001 From: Dan Ditomaso Date: Sun, 18 Oct 2026 16:32:05 -0400 Subject: [PATCH 4/4] docs(e2e): take the pnpm version from the root packageManager pin e2e/README.md asked for pnpm 11.5.2 while the root pins 11.9.0. Point at the pin instead of repeating a version that drifts. Raised by CodeRabbit on #1406. --- e2e/README.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) 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