Skip to content

Contributing to Micromegas

We welcome contributions to the Micromegas project! Here are some ways you can contribute:

Reporting Bugs

If you find a bug, please open an issue on our GitHub Issues page. Please include:

  • A clear and concise description of the bug.
  • Steps to reproduce the behavior.
  • Expected behavior.
  • Screenshots or error messages if applicable.
  • Your operating system and Micromegas version.

Suggesting Enhancements

We're always looking for ways to improve Micromegas. If you have an idea for a new feature or an improvement to an existing one, please open an issue on our GitHub Issues page. Please include:

  • A clear and concise description of the enhancement.
  • Why you think it would be valuable to the project.
  • Any potential use cases.

Code Contributions

We welcome code contributions! If you'd like to contribute code, please follow these steps:

  1. Fork the repository and clone it to your local machine.
  2. Create a new branch for your feature or bug fix: git checkout -b feature/your-feature-name or git checkout -b bugfix/your-bug-fix-name.
  3. Make your changes and ensure your code adheres to the project's coding style and conventions.
  4. Write tests for your changes, if applicable.
  5. Run existing tests to ensure nothing is broken.
  6. Commit your changes with a clear and concise commit message.
  7. Push your branch to your forked repository.
  8. Open a Pull Request to the main branch of the Micromegas repository. Please provide a detailed description of your changes.

Development Setup

For information on setting up your local development environment — including building from source and running a development instance of the services — please refer to the Build Guide.

Monorepo Structure

Micromegas uses a monorepo structure with Yarn workspaces for JavaScript/TypeScript components and Cargo workspaces for Rust components.

Repository Layout

micromegas/
├── rust/                    # Rust workspace (main application)
│   ├── Cargo.toml          # Root Cargo workspace
│   ├── analytics/          # Analytics engine
│   ├── tracing/            # Instrumentation library
│   ├── telemetry-ingestion-srv/
│   ├── flight-sql-srv/
│   └── ...
├── analytics-web-app/      # Analytics web UI (Vite + React 19)
│   ├── package.json
│   └── src/
├── grafana/                # Grafana datasource plugin
│   ├── package.json
│   ├── src/
│   └── pkg/                # Go backend
├── typescript/             # Shared TypeScript packages
│   └── types/              # @micromegas/types package
├── python/                 # Python client
│   └── micromegas/         # Poetry package
├── package.json            # Root Yarn workspace
└── CONTRIBUTING.md         # This file

Rust Workspace (Primary)

The Rust workspace is located in rust/ and contains the core Micromegas platform. This is the main workspace of the project.

Commands (run from rust/ directory): 

cargo build              # Build all crates
cargo test               # Run all tests
cargo fmt                # Format code (REQUIRED before commit)
cargo clippy --workspace -- -D warnings  # Lint

CI validation script: 

python3 build/rust_ci.py    # Runs format check, clippy, and tests (from repo root)

Python Package

The Python client uses Poetry for dependency management.

Location: python/micromegas/

Commands (run from python/micromegas/): 

poetry install          # Install dependencies
poetry run pytest       # Run tests
poetry run black <file> # Format code (REQUIRED before commit)

CI validation script: 

python3 build/python_ci.py    # Runs the hermetic test subset and black --check (from repo root)

Analytics Web App

The analytics web UI is a standalone Vite + React 19 application in analytics-web-app/.

Location: analytics-web-app/

Prerequisites: Run corepack enable once per machine to activate the pinned Yarn version.

Commands (run from analytics-web-app/): 

corepack enable         # Once per machine
yarn install            # Install dependencies
yarn dev                # Dev server on port 3000 (Vite)
yarn build              # Production build to dist/
yarn lint               # ESLint
yarn type-check         # TypeScript type check (no emit)
yarn test               # Vitest unit tests

TypeScript/JavaScript Workspaces

The repository uses Yarn workspaces to manage the Grafana plugin and shared TypeScript packages.

  • Root workspace (package.json): Defines workspaces and shared dev dependencies
  • grafana/: Grafana FlightSQL datasource plugin (React + Go backend)
  • typescript/types/: Shared TypeScript type definitions (@micromegas/types)

Important: Always use yarn, not npm, to avoid lockfile conflicts. Run corepack enable once per machine before running yarn install.

Working with All Components

Installing Dependencies

Rust (from rust/ directory): 

cargo build              # Fetches and compiles Rust dependencies

Python (from python/micromegas/ directory): 

poetry install           # Installs Python dependencies

TypeScript/JavaScript (from repository root, use yarn; run corepack enable first if needed): 

yarn install             # Install all workspace dependencies (Grafana plugin, shared types)

Analytics web app (standalone workspace in analytics-web-app/): 

cd analytics-web-app && yarn install

Go (for Grafana backend, from grafana/ directory): 

go mod download          # Downloads Go dependencies

Building Components

Rust workspace: 

cd rust && cargo build                   # Build all Rust crates

Python package: 

cd python/micromegas && poetry install   # Python doesn't need a build step

TypeScript/JavaScript workspaces (use yarn): 

yarn workspaces foreach -A run build     # Build all workspaces (from root)
cd grafana && yarn build                 # Grafana plugin only
cd typescript/types && yarn build        # Shared types only

Analytics web app: 

cd analytics-web-app
yarn build              # Production build to dist/
yarn dev                # Vite dev server on port 3000

Running Tests

Rust workspace: 

cd rust && cargo test                    # All Rust tests
python3 build/rust_ci.py                 # Rust CI validation (from root)

Python package: 

cd python/micromegas && poetry run pytest  # Python tests
python3 build/python_ci.py                 # Python CI validation (from root)

TypeScript/JavaScript workspaces (use yarn): 

yarn workspaces foreach -A run test      # Test all workspaces (from root)
cd grafana && yarn test:ci               # Grafana plugin tests only

Analytics web app: 

cd analytics-web-app && yarn test        # Vitest unit tests

Linting

Rust workspace: 

cd rust && cargo clippy --workspace -- -D warnings
cd rust && cargo fmt                     # Format (REQUIRED before commit)

Python package: 

cd python/micromegas && poetry run black .

TypeScript/JavaScript workspaces (use yarn): 

yarn workspaces foreach -A run lint      # Lint all workspaces (from root)
cd grafana && yarn lint:fix              # Grafana plugin only

Analytics web app: 

cd analytics-web-app && yarn lint        # ESLint
cd analytics-web-app && yarn type-check  # TypeScript check (no emit)

Grafana Plugin Development

The Grafana plugin requires both Node.js and Go:

Prerequisites: - Node.js 22+ (matches grafana/.nvmrc and the grafana-plugin CI workflow; Yarn 4 requires ≥18.12) - Go 1.25+ (matches grafana/go.mod and the grafana-plugin CI workflow's go-version: '1.25') - corepack enable — activates the pinned Yarn version (run once per machine) - mage (for Go builds): go install github.com/magefile/mage@latest

mage coverage needs a covdata binary in GOROOT

If your system Go is older than grafana/go.mod's version, GOTOOLCHAIN=auto downloads a matching toolchain automatically — but that auto-downloaded toolchain ships a trimmed tool set (asm cgo compile cover link preprofile vet only) and omits covdata, pprof, trace, and others. go test -coverpkg ./... (which mage coverage runs) needs covdata to merge coverage across packages, and unlike the interactive go tool covdata command, its internal invocation does not fall back to building the tool on demand — it fails with go: no such tool "covdata" even though every individual test passes. Installing a Go SDK that already satisfies go.mod (so no toolchain auto-download is needed) doesn't fully fix this either, since even the official go1.25.x tarball omits a prebuilt covdata. Build it once into your GOROOT: 

GOROOT=$(go env GOROOT)
cd "$GOROOT/src/cmd/covdata"
go build -o "$GOROOT/pkg/tool/$(go env GOOS)_$(go env GOARCH)/covdata" .

Development workflow: 

cd grafana

# Install dependencies
yarn install

# Build Go backend binaries
mage -v build

# Start development server with hot reload
yarn dev

# Run tests
yarn test:ci

# Run linting
yarn lint

# Build production bundle
yarn build

Starting Grafana with the plugin: 

cd grafana
yarn server             # Starts Grafana with docker compose (includes --build)
# Access Grafana at http://localhost:3000

Code Style and Conventions

Rust

  • Dependencies in alphabetical order in Cargo.toml files
  • Error handling: Use expect() with descriptive messages in tests, use anyhow in library code
  • Run cargo fmt before any commit
  • Use inline format arguments: format!("value: {variable}")
  • Always use prelude::* when importing from prelude modules

TypeScript/JavaScript

  • Follow existing ESLint configuration in each workspace
  • Use Prettier for formatting
  • Run yarn lint:fix before committing
  • Prefer functional components and hooks in React code

Python

  • Use Black for formatting (required before commit)
  • Follow PEP 8 guidelines
  • Use type hints where appropriate

Commit Messages

  • Keep messages clear and concise
  • Follow existing commit message patterns in the repository

Thank you for contributing to Micromegas!