# Contributing to WorldWideView Thank you for your interest in contributing to **WorldWideView** โ€” a modular, real-time geospatial intelligence engine! This project is licensed under the [Elastic License 2.0](./LICENSE). By submitting a contribution, you agree that your code will be made available under those same terms. --- ## Table of Contents - [Getting Started](#getting-started) - [Development Setup](#development-setup) - [Project Structure](#project-structure) - [How to Contribute](#how-to-contribute) - [Plugin Contributions](#plugin-contributions) - [Code Standards](#code-standards) - [Commit & Branch Conventions](#commit--branch-conventions) - [Pull Request Process](#pull-request-process) - [Running Tests](#running-tests) --- ## Getting Started 1. **Fork** the repository on GitHub. 2. **Clone** your fork locally: ```bash git clone https://github.com//worldwideview.git cd worldwideview ``` 3. **Install dependencies**: ```bash npm install ``` 4. **Generate environment file** (auto-creates `.env.local` with `AUTH_SECRET`): ```bash npm run setup ``` 5. **Start the dev server**: ```bash npm run dev ``` Visit `http://localhost:3000` to confirm everything is running. --- ## Development Setup | Requirement | Version | |-------------|---------| | Node.js | 18+ | | npm | 9+ | See [`docs/SETUP.md`](docs/SETUP.md) for detailed environment setup, including Cesium Ion token configuration. --- ## Project Structure ``` src/ core/ # Core engine: state, data bus, plugin registry plugins/ # Data source plugins (ADS-B, AIS, satellites, etc.) components/ # React UI components hooks/ # Custom React hooks docs/ # Architecture and user guides ``` See [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) for a deep dive into the rendering pipeline and plugin lifecycle. --- ## How to Contribute Ways you can help: - ๐Ÿ› **Bug fixes** โ€” Check the [issue tracker](https://github.com/silvertakana/worldwideview/issues) - ๐Ÿงฉ **New plugins** โ€” Add a new data source layer (see below) - ๐Ÿ“– **Documentation** โ€” Improve guides or add examples - โšก **Performance** โ€” Cesium primitive optimizations, GPU stall reduction - ๐Ÿงช **Tests** โ€” Expand Vitest coverage For large features, **open an issue first** to discuss the design before writing code. --- ## Plugin Contributions The core extension point of WorldWideView is its **plugin system**. Each plugin is a self-contained data layer that: 1. Fetches or subscribes to a data source 2. Transforms raw data into Cesium-ready primitives 3. Registers itself with the `PluginRegistry` See [`docs/PLUGIN_GUIDE.md`](docs/PLUGIN_GUIDE.md) for a full walkthrough. New plugins are very welcome โ€” if you have access to a live geospatial data feed, a plugin is the best way to contribute. --- ## Code Standards This project follows these principles: - **Single Responsibility Principle** โ€” each file/module does one thing - **DRY & SOLID** โ€” avoid duplication, favour composition - **Clean Architecture** โ€” UI, logic, and data are separate concerns - **Defensive Programming** โ€” validate inputs, handle edge cases explicitly - **File size** โ€” keep files under 150 lines; split into modules if needed Use TypeScript strictly. Avoid `any` unless absolutely unavoidable. --- ## Commit & Branch Conventions **Branch naming:** ``` feat/short-description fix/short-description docs/short-description refactor/short-description ``` **Commit messages** follow [Conventional Commits](https://www.conventionalcommits.org/): ``` feat: add maritime AIS plugin fix: resolve camera snap on globe reset docs: update plugin guide with lifecycle diagram refactor: extract billboard factory from CesiumMap ``` --- ## Pull Request Process 1. Ensure your branch is up to date with `main`. 2. Run tests and confirm they pass: `npm test` 3. Fill out the [PR template](.github/PULL_REQUEST_TEMPLATE.md) completely. 4. Request a review โ€” PRs need at least one approval before merging. 5. Squash commits on merge if the history is noisy. --- ## Running Tests ```bash npm test # Run all tests via Vitest npm run test:ui # Open Vitest UI (interactive) ``` Tests live alongside source files in `__tests__/` directories or as `.test.ts` files.