Contributing to ODS-E

ODS-E is an open specification and we welcome contributions from the energy data community. Whether you’re fixing a typo, adding support for a new OEM, or improving documentation, this guide will help you get started.

Environment Setup

Prerequisites

• Python 3.9+
• Git
• A GitHub account

Getting Started

# Fork and clone the repository
git clone https://github.com/<your-username>/odse.git
cd odse

# Install in development mode with dev dependencies
pip install -e ".[dev]"

# Install pre-commit hooks
pre-commit install

# Verify your setup
odse --version
pytest

Development Tools

All of these run automatically in CI, but running them locally before pushing saves time.

Ways to Contribute

Documentation Improvements

The lowest barrier way to contribute. Documentation lives alongside the code and is always in need of:

• Fixing typos and grammar
• Improving clarity of explanations
• Adding code examples
• Updating screenshots or diagrams

How to start: Look for issues labelled docs or good-first-issue, or simply open a PR with your improvement.

Adding & Labelling Issues

Good issue reports are extremely valuable. When filing an issue:

Bug reports should include:

• OEM and data format (e.g., “Huawei FusionSolar CSV export”)
• Python version and odse version (odse --version)
• Minimal reproduction steps
• Expected vs actual output
• Sample data (anonymized — see Data Privacy below)

Feature requests should include:

• The problem you’re trying to solve
• Your proposed solution (if you have one)
• Which OEMs or schemas are affected

Label taxonomy:

Adding Transforms for New OEMs

This is the most impactful type of contribution. Each new OEM transform makes ODS-E useful to a wider community.

Before you start:

1. Check existing transforms to see if your OEM is already supported
2. Search open issues and PRs to avoid duplicate work
3. Open an issue describing the OEM and data format you plan to support

Submission checklist:

• Transform YAML spec following the transform specification format
• Sample input file (anonymized)
• Expected output file in ODS-E format
• Test cases covering normal operation, error states, and edge cases
• Documentation of OEM-specific quirks (timestamp formats, encoding, units)

Naming convention:

transforms/
├── oem-product.yaml          # e.g., huawei-fusionsolar.yaml
tests/transforms/
├── test_oem_product.py       # e.g., test_huawei_fusionsolar.py
├── fixtures/
│   ├── oem-product-input.*   # Sample input
│   └── oem-product-expected.json  # Expected output

For full details on the YAML spec format, field mappings, and error code mappings, see the Transform Specifications page.

Updating Existing OEM Transforms

OEMs periodically change their export formats, API responses, or error codes. When you encounter a change:

1. Identify the change — What fields moved, were added, or changed format?
2. Update the YAML spec — Modify the relevant transforms/*.yaml file
3. Update error code mappings — If new error codes appeared, classify them into the 7-category error taxonomy
4. Add regression tests — Ensure the old format still works (if the OEM supports both) and the new format is handled correctly
5. Document the change — Note the OEM firmware/software version where the format changed

PR Protocol

Workflow

1. Fork the repository
2. Branch from main with a descriptive name
3. Commit your changes with clear messages
4. Push to your fork
5. Open a PR against main

Branch Naming

Commit Messages

Use conventional commits and reference the issue number:

feat: add SMA Sunny Portal transform (#58)
fix: handle Huawei timezone offset in CSV export (#42)
docs: add Enphase Envoy API examples (#61)

PR Requirements

Every PR must:

• Pass CI — Schema validation, tests, and linting must all be green
• Have a clear description — What changed, why, and how to test it
• Include tests — For code changes, not just documentation
• Be focused — One transform or one fix per PR; don’t mix unrelated changes
• Receive at least one maintainer review before merging

Good vs Bad Contributions

What makes a good contribution

• Focused and single-purpose — One PR does one thing well
• Tested — Includes unit tests with sample input/output data
• Follows existing patterns — Uses the same YAML spec format, error taxonomy categories, and code style as existing transforms
• Anonymized data — Sample data contains no real site names, GPS coordinates, or customer information
• Clear commit messages — References the relevant issue and describes the “why”
• Responsive to review — Addresses feedback promptly and constructively

What makes a bad contribution

• Kitchen-sink PRs — Multiple unrelated changes bundled together
• Missing tests — Code without corresponding test cases
• New error categories — ODS-E uses exactly 7 error categories (normal, warning, critical, fault, offline, standby, unknown). Don’t invent new ones; map OEM codes into the existing taxonomy
• Real production data — Never include identifiable customer data in samples
• Ignoring CI — PRs with failing linter or test runs won’t be reviewed

Data Privacy

When including sample data in your contribution:

• Remove real site names, asset IDs, and customer references
• Randomize GPS coordinates (or use 0.0, 0.0)
• Keep realistic data patterns (timestamps, power values, error codes)
• Limit sample files to 10-50 rows — enough to test, not enough to identify

Getting Help

If you’re stuck, have questions, or want to discuss an idea before starting work:

• Discord — Join our community for real-time discussion with maintainers and other contributors
• GitHub Issues — For bugs, feature requests, and technical questions
• Email — support@asoba.co for sensitive or security-related matters

Get Help & Stay Updated