Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
151 lines (108 loc) · 4.25 KB

CONTRIBUTING.md

File metadata and controls

151 lines (108 loc) · 4.25 KB
Raw

Contributing to Linje.track

Thank you for your interest in contributing to Linje.track — 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

  1. Fork the repository on GitHub.
  2. Clone your fork locally: 
    git clone https://github.com/<your-username>/worldwideview.git
cd worldwideview
  3. Install dependencies: 
    npm install
  4. Generate environment file (auto-creates .env.local with AUTH_SECRET): 
    npm run setup
  5. 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 Linje.track 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 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

  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 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

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.