Contributing to Micromegas¶

We welcome contributions to the Micromegas project! This guide will help you get started with contributing code, documentation, or reporting issues.

Code of Conduct¶

By participating in this project, you agree to maintain a respectful and inclusive environment for all contributors.

Getting Started¶

Development Setup¶

Clone the repository:

git clone https://github.com/madesroches/micromegas.git
cd micromegas

Set up development environment: Follow the Getting Started Guide to set up your local environment.

Install development dependencies:

# Rust development
cd rust
cargo build

# Python development
cd python/micromegas
poetry install

Contributing Code¶

Before You Start¶

Check existing issues on GitHub Issues
Open an issue to discuss your proposed changes if it's a significant feature
Fork the repository and create a feature branch

Development Workflow¶

Create a feature branch:

git checkout -b feature/your-feature-name
# or
git checkout -b bugfix/issue-description

Follow coding standards (see AI Guidelines):
Rust: Run cargo fmt before any commit
Python: Use black for formatting
Dependencies: Keep alphabetical order in Cargo.toml
Error handling: Use expect() with descriptive messages instead of unwrap()
Start development services:

For testing and development, you can start all required services (PostgreSQL, telemetry-ingestion-srv, flight-sql-srv, and telemetry-admin) using the dev.py script:

# Start all services in a tmux session (debug mode)
python3 local_test_env/dev.py

# Or in release mode for better performance
python3 local_test_env/dev.py release

This will: - Build the Rust services - Start PostgreSQL database - Start telemetry-ingestion-srv on port 9000 - Start flight-sql-srv on port 32010
- Start telemetry-admin service - Open a tmux session with all services running in separate panes

To stop all services:

# Use the stop script
python3 local_test_env/stop-dev.py

# Or manually kill the tmux session
tmux kill-session -t micromegas

Write tests:

# Rust tests
cd rust
cargo test

# Python tests
cd python/micromegas
pytest

Run CI pipeline locally:
```
cd rust
python3 ../build/rust_ci.py
```

Commit with clear messages:

git commit -m "Add histogram generation for span duration analysis"

Create Pull Request: Once your changes are ready, create a pull request on GitHub.

Code Review Process¶

Automated checks: Ensure all CI checks pass
Code review: Maintainers will review your changes
Address feedback: Make requested changes if needed
Merge: Once approved, your PR will be merged

Contributing Documentation¶

Setup¶

Install documentation dependencies:

# Create and activate virtual environment (recommended)
python3 -m venv docs-venv
source docs-venv/bin/activate  # On Windows: docs-venv\Scripts\activate

# Install dependencies
pip install -r docs/docs-requirements.txt

MkDocs Documentation¶

The main documentation uses MkDocs with Material theme:

Edit documentation:
Files are in mkdocs/docs/ directory
Configuration in mkdocs/mkdocs.yml
Use Markdown format
Follow existing structure and style

Preview changes:

cd mkdocs

# Using the virtual environment
/home/mad/micromegas/docs-venv/bin/mkdocs serve --dev-addr=0.0.0.0:8000

# Or if mkdocs is in your PATH
mkdocs serve

# Visit http://localhost:8000

Build documentation:

cd mkdocs
/home/mad/micromegas/docs-venv/bin/mkdocs build

# Output will be in mkdocs/site/

Deploy documentation:

# Documentation is automatically deployed via GitHub Actions
# when changes are pushed to the main branch

Documentation Guidelines¶

Clear and concise: Write for your audience
Code examples: Include working examples with expected output
Cross-references: Link to related sections
Consistent formatting: Follow existing patterns

Reporting Issues¶

Bug Reports¶

Include the following information:

Environment: OS, Rust version, Python version
Micromegas version: Git commit or release version
Steps to reproduce: Clear, minimal reproduction steps
Expected vs actual behavior: What should happen vs what happens
Logs/errors: Include relevant error messages or logs
Configuration: Relevant environment variables or config

Feature Requests¶

Use case: Describe the problem you're trying to solve
Proposed solution: Your suggested approach
Alternatives: Other approaches you've considered
Impact: Who would benefit from this feature

Development Guidelines¶

Architecture Understanding¶

Familiarize yourself with the architecture overview:

High-performance instrumentation (20ns overhead)
Lakehouse architecture with object storage
DataFusion-powered analytics
FlightSQL protocol for efficient data transfer

Key Areas for Contribution¶

Core Rust Libraries:
Tracing instrumentation improvements
Analytics engine enhancements
Performance optimizations
Services:
Ingestion service features
FlightSQL server improvements
Admin CLI enhancements
Client Libraries:
Python API improvements
New language bindings
Documentation:
Query examples and patterns
Performance guidance
Integration guides
Testing:
Unit test coverage
Integration tests
Performance benchmarks

Performance Considerations¶

Benchmarking: Include benchmarks for performance-critical changes
Memory usage: Consider memory implications of new features
Backwards compatibility: Maintain API compatibility when possible

Security¶

No secrets in code: Never commit API keys, passwords, or tokens
Input validation: Validate all external inputs
Dependencies: Keep dependencies updated and minimal

Community¶

Getting Help¶

Documentation: Check the documentation first
GitHub Issues: Search existing issues before creating new ones
Discussions: Use GitHub Discussions for questions and ideas

Stay Updated¶

Watch the repository for updates
Follow releases for new features and bug fixes
Join discussions about future directions

Recognition¶

Contributors are recognized in: - Git commit history - Release notes for significant contributions - Special thanks in documentation

Thank you for contributing to Micromegas! Your contributions help make observability more accessible and cost-effective for everyone.