151 lines
4.4 KiB
Markdown
151 lines
4.4 KiB
Markdown
# Contributing to Meshtastic Web
|
||
|
||
Thank you for your interest in contributing to **Meshtastic Web**! 🎉
|
||
We welcome all contributions—whether it’s fixing a typo, improving documentation, adding new features, or reporting bugs. This document outlines how to get started and the conventions we follow.
|
||
|
||
---
|
||
|
||
## 📋 Code of Conduct
|
||
We follow the [Meshtastic Code of Conduct](https://meshtastic.org/docs/legal/conduct/).
|
||
Please make sure you are familiar with it before contributing.
|
||
|
||
---
|
||
|
||
## 🚀 Getting Started
|
||
Before making changes, please take some time to explore the repository and its monorepo structure.
|
||
Understanding how the packages are organized will make it much easier to contribute effectively.
|
||
|
||
[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)
|
||
- Git
|
||
|
||
### Installation
|
||
Clone the repo and install dependencies:
|
||
|
||
```bash
|
||
git clone https://github.com/meshtastic/web.git meshtastic-web
|
||
cd meshtastic-web
|
||
pnpm install
|
||
```
|
||
|
||
### Development
|
||
Start the development server:
|
||
|
||
```bash
|
||
pnpm --filter @meshtastic/web dev
|
||
```
|
||
|
||
Once running, the site will be available at:
|
||
👉 **http://localhost:3000**
|
||
|
||
---
|
||
|
||
## 🗂 Repository Structure
|
||
Meshtastic Web uses a **monorepo** setup managed with **pnpm workspaces**:
|
||
|
||
```
|
||
/packages
|
||
├─ web # React frontend
|
||
├─ core # Shared types & logic
|
||
├─ transport-* # Transport layer packages
|
||
└─ ...other packages
|
||
```
|
||
|
||
---
|
||
|
||
## ✅ Contribution Workflow
|
||
|
||
1. **Fork the repo** and create your branch from `main`.
|
||
|
||
### Branch Naming
|
||
- Use [Conventional Commit](https://www.conventionalcommits.org/) style for your branch names:
|
||
```
|
||
feat/add-project-filter
|
||
fix/storage-service
|
||
chore/update-ci-cache
|
||
```
|
||
|
||
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.
|
||
|
||
4. **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.
|
||
- All checks must pass before merge.
|
||
|
||
---
|
||
|
||
## 🌍 Internationalization (i18n)
|
||
|
||
Meshtastic Web supports multiple languages. If your changes introduce **new user-facing strings**:
|
||
|
||
- Add them to the **`en.json`** file.
|
||
- 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)
|
||
|
||
---
|
||
|
||
## 🧪 Testing
|
||
Tests are written with [Vitest](https://vitest.dev/).
|
||
|
||
Run all tests locally with:
|
||
|
||
```bash
|
||
pnpm --filter @meshtastic/web test
|
||
```
|
||
|
||
Please include tests for new features and bug fixes whenever possible.
|
||
|
||
---
|
||
|
||
## 📝 Commit Messages
|
||
We use **Conventional Commits**:
|
||
|
||
- `feat:` – a new feature
|
||
- `fix:` – a bug fix
|
||
- `docs:` – documentation changes
|
||
- `chore:` – maintenance, dependencies, build scripts
|
||
- `refactor:` – code restructuring without feature changes
|
||
- `test:` – adding or updating tests
|
||
- `ci:` – CI/CD changes
|
||
|
||
Example:
|
||
```
|
||
feat: add toast notification system
|
||
fix: correct caching issue in storage service
|
||
```
|
||
|
||
---
|
||
|
||
## 💡 Tips for Contributors
|
||
- Keep PRs **small, focused, and atomic**.
|
||
- Discuss larger changes with the team on [Discord](https://discord.gg/meshtastic) before starting work.
|
||
- If unsure, open a draft PR for early feedback.
|
||
|
||
---
|
||
|
||
## 🙌 Community
|
||
Contributors are the heart of Meshtastic ❤️.
|
||
Join the conversation:
|
||
- [Discord](https://discord.gg/meshtastic)
|
||
- [GitHub Discussions](https://github.com/meshtastic/web/discussions)
|
||
|
||
---
|
||
|
||
## 📜 License
|
||
By contributing, you agree that your contributions will be licensed under the [GPL-3.0-only License](../../LICENSE).
|