4.3 KiB
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. By submitting a contribution, you agree that your code will be made available under those same terms.
Table of Contents
- Getting Started
- Development Setup
- Project Structure
- How to Contribute
- Plugin Contributions
- Code Standards
- Commit & Branch Conventions
- Pull Request Process
- Running Tests
Getting Started
- Fork the repository on GitHub.
- Clone your fork locally:
git clone https://github.com/<your-username>/worldwideview.git cd worldwideview - Install dependencies:
npm install - Generate environment file (auto-creates
.env.localwithAUTH_SECRET):npm run setup - Start the dev server:
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 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 for a deep dive into the rendering pipeline and plugin lifecycle.
How to Contribute
Ways you can help:
- 🐛 Bug fixes — Check the issue tracker
- 🧩 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:
- Fetches or subscribes to a data source
- Transforms raw data into Cesium-ready primitives
- Registers itself with the
PluginRegistry
See 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:
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
- Ensure your branch is up to date with
main. - Run tests and confirm they pass:
npm test - Fill out the PR template completely.
- Request a review — PRs need at least one approval before merging.
- Squash commits on merge if the history is noisy.
Running Tests
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.