Contributing

Contribution guidelines, development setup, code review standards, and security disclosure procedures

Thank you for your interest in contributing to OMEN. This page covers the contribution workflow, development environment setup, code review standards, and security disclosure procedures.

Getting Started

Prerequisites

Development Setup

# Clone the repository
git clone https://github.com/DaScient/OMEN.git
cd OMEN

# Install Python dependencies
pip install pydantic>=2.0 pytest>=7.0 pytest-asyncio>=0.21

# Run tests to verify setup
PYTHONPATH=. pytest engine/core/ examples/ evaluation/ -v -k "not docker"

Contribution Workflow

1. Fork & Branch

# Fork on GitHub, then:
git clone https://github.com/YOUR_USERNAME/OMEN.git
cd OMEN
git checkout -b feature/my-feature develop

2. Implement & Test

• Write your changes following existing code style
• Add tests for new functionality
• Ensure all existing tests pass

3. Lint & Validate

# Python linting
ruff check . --select E,W,F --ignore E501

# Run tests
PYTHONPATH=. pytest engine/core/ examples/ evaluation/ -v -k "not docker"

4. Commit & Push

git add .
git commit -m "feat: description of your change"
git push origin feature/my-feature

5. Pull Request

• Reference the issue your PR addresses
• Describe the changes clearly
• Request review from maintainers
• Ensure automated checks pass

6. Code Review

• Address all reviewer feedback
• Automated checks must pass (CI, linting, tests)
• Security-sensitive changes require a security reviewer

7. Merge

• Maintainers squash-merge to develop
• Release branches are cherry-picked to main

Code Style

Python

• Follow PEP 8 (enforced by ruff)
• Use type hints for all function signatures
• Use Pydantic v2 for data models
• Use pytest for testing
• Line length: flexible (E501 not enforced), but be reasonable

TypeScript

• Follow existing ESLint configuration
• Use TypeScript strict mode
• Mirror Python interfaces where applicable

Documentation

• Use Markdown for all documentation
• Keep docs updated when changing code
• Include code examples where helpful

Testing Requirements

All PRs Must:

• Pass existing tests without modification (unless fixing a bug in them)
• Add tests for new functionality
• Maintain or improve code coverage

Test Commands

# Engine core tests
PYTHONPATH=. pytest engine/core/test_core.py -v

# Sample adapter tests
PYTHONPATH=. pytest examples/sample-adapter/test_adapter.py -v

# Sample plugin tests
PYTHONPATH=. pytest examples/sample-plugin/test_plugin.py -v

# Evaluation harnesses
PYTHONPATH=. pytest evaluation/ -v -k "not docker"

# All tests
PYTHONPATH=. pytest engine/core/ examples/ evaluation/ -v -k "not docker"

Security Disclosure

Do NOT file public GitHub issues for security vulnerabilities.

If you discover a security vulnerability in OMEN:

1. Email the maintainers at the address listed in SECURITY.md (if available)
2. Include:
   • Description of the vulnerability
   • Steps to reproduce
   • Potential impact assessment
   • Suggested remediation (if any)
3. Timeline:
   • Acknowledgment within 48 hours
   • Initial assessment within 5 business days
   • Coordinated disclosure after fix is available

Contributor License Agreement (CLA)

By contributing to OMEN, you agree that your contributions may be used under the Apache 2.0 License.

Community Standards

• Be respectful and constructive in all communications
• Follow the Code of Conduct (if available)
• Help newcomers feel welcome
• Assume good intent in discussions

What to Contribute

Good First Contributions

• Documentation improvements
• Test coverage expansion
• Adapter stubs (KML, NOTAM, UDL)
• Bug fixes with reproduction steps

Intermediate Contributions

• New adapter implementations
• Plugin development
• Evaluation harness extensions
• CI/CD pipeline improvements

Advanced Contributions

• CAL normalization pipeline
• Engine service orchestration
• Map-app component development
• Security hardening