Contribution Process Overview

We welcome contributions of code, documentation, or issue feedback to EnerOS. EnerOS is a native AgentOS for the power and energy domain, consisting of 56 Rust crates that cover the complete stack from kernel to application. This page outlines the full contribution process; detailed specifications are in the subsequent sections.

Contributor Types

The EnerOS community welcomes contributors from different backgrounds. The table below lists different roles and their typical work:

Maintainer Hierarchy

Contribution Methods

Code Contributions

Code contributions are the most direct way to contribute to EnerOS, covering the following directions:

Documentation Contributions

Documentation contributions have a low barrier and broad impact, making them the best starting point for first-time contributions:

• Fix typos, broken links, and formatting issues
• Add example code and configuration snippets
• Write tutorials and best practices for new features
• Translate documentation to English, Japanese, Spanish

See Documentation Contribution Guide for details.

Test Contributions

EnerOS has 7300+ test cases, but additional contributions are still welcome:

• Add unit tests for uncovered code paths
• Add edge cases and exception scenarios
• Add IEEE standard reference data
• Write performance benchmarks

See Testing Standards for details.

Issue Contributions

High-quality Issues are the starting point for project improvement:

Review Contributions

Review is a core form of community contribution. Reviewers should focus on:

1. Correctness: Does the algorithm align with power domain knowledge? Are boundary conditions covered?
2. Security: Does it bypass the constraint engine or audit chain? Does it introduce new plaintext channels?
3. Performance: Does the hot path introduce unnecessary allocations? Does it block the async runtime?
4. Maintainability: Are names clear? Does the public API need documentation?
5. Test Sufficiency: Do tests cover failure paths? Do they depend on the external environment?

Overall Process

Issue → Fork → Branch → Develop & Test → PR → Review → Merge

Step Details

1. Find or Create an Issue

Confirm there is no duplicate in GitHub Issues before creating a new one. Issue titles must be concise and clear, and the body must follow the template:

## Problem Description
(A paragraph describing the problem encountered or the expected capability)

## Reproduction Steps
1. Go to ...
2. Execute ...
3. Observe ...

## Expected Behavior
(What should happen)

## Actual Behavior
(What actually happened, with logs or screenshots)

## Environment
- EnerOS version:
- Operating system:
- Rust version:

2. Fork and Clone

# Click Fork on the GitHub web page, then:
git clone https://github.com/<your-account>/EnerOS.git
cd EnerOS

# Add the upstream repository for subsequent syncing
git remote add upstream https://github.com/Gawg-AI/EnerOS.git
git fetch upstream

# Verify remote configuration
git remote -v
# origin    https://github.com/<your-account>/EnerOS.git (fetch)
# origin    https://github.com/<your-account>/EnerOS.git (push)
# upstream  https://github.com/Gawg-AI/EnerOS.git (fetch)
# upstream  https://github.com/Gawg-AI/EnerOS.git (push)

3. Create a Branch

Branch out from the latest main, with naming following these conventions:

# Sync upstream main
git checkout main
git pull upstream main

# Create a feature branch
git checkout -b feat/powerflow-pv-limits

4. Develop and Test Locally

# After writing code, run the following checks
cargo fmt --all
cargo clippy --all-targets -- -D warnings
cargo nextest run
cargo nextest run -p eneros-powerflow

# If public API changes are involved, verify documentation builds
cargo doc --no-deps --all-features

See Development Environment and Testing Standards for details.

5. Submit a PR

Commit messages must conform to Conventional Commits:

git add crates/eneros-powerflow/src/solver.rs crates/eneros-powerflow/tests/solver_test.rs
git commit -m "feat(powerflow): support PV bus reactive power limits

- Add q_min/q_max fields to PvBus
- NewtonRaphsonSolver auto-converts to PQ node on reactive power violation
- Add 5 test cases covering violation scenarios

Closes #123"

Push to your personal fork:

git push origin feat/powerflow-pv-limits

Create a PR on the GitHub web page, fill out the PR template, and link the Issue. See Pull Request Process for details.

6. Respond to Review

• Reply to or address each comment; do not ignore them
• For major changes, prefer git push --force-with-lease over merge commits to keep history linear
• PRs inactive for a long time (>30 days) will be closed and can be reopened at any time

7. Merge

After passing CI and approval from at least one Reviewer, the Maintainer will merge. After merging, the branch will be deleted by the Maintainer and the linked Issue will be automatically closed.

CLA Requirements

Contributors must sign a Contributor License Agreement (CLA) to ensure the EnerOS community has legal rights to use, modify, and re-license the contributed code.

Individual CLA

For individual contributors, the signing process is:

1. Read the agreement on the CLA signing page
2. Log in with your GitHub account
3. Confirm your identity (name and email must match your GitHub username)
4. Sign online; it takes effect immediately upon submission

Key terms of the Individual CLA:

Corporate CLA

For enterprise employees contributing on behalf of the company. Must be signed by the company’s legal counsel or authorized representative:

1. Download the agreement PDF from the Corporate CLA page
2. Sign by the authorized representative and affix the company seal
3. Mail or scan and send to cla@openeneros.com
4. Staff will verify and register within 5 business days

CLA Verification

After each PR is submitted, the CLAssistant bot will automatically check the signing status:

• Signed: Shows ✅, can continue the Review process
• Not signed: Shows ❌ with a signing link; must be signed within 7 days

If you have questions about the CLA, please email cla@openeneros.com.

Code of Conduct

The EnerOS community follows the Contributor Covenant 2.1 Code of Conduct. The following is a summary of key terms; see CODE_OF_CONDUCT.md for the full text.

Core Commitments

• Respect: Respect all contributors; no personal attacks, discrimination, or harassment of any kind
• Focus on Technology: Discussions should focus on technical issues, addressing problems not people
• Confidentiality: Keep customer data and grid topology information confidential; do not share on public channels
• Inclusivity: Welcome contributors from different backgrounds and skill levels

Unacceptable Behavior

Reporting Channels

If you observe violations of the Code of Conduct, please report through the following channels:

• Email: conduct@openeneros.com
• Private message: Any Maintainer’s GitHub private message
• Emergency security incidents: security@openeneros.com

All reports will be kept confidential, and reporters will not face retaliation. The maintenance committee will respond and handle the matter within 7 business days.

First Contribution Guide

Recommended Starter Tasks

First-time contributors are advised to start with the following tasks:

Filter by the good first issue label on the GitHub Issues page to see recommended tasks.

First Contribution Checklist

• Read the “Overall Process” and “Code of Conduct” sections on this page
• Signed the Individual CLA
• Forked the repository and completed the local build
• Selected a good first issue task and commented to claim it on the Issue
• Created a branch following the naming conventions
• Passed cargo fmt, cargo clippy, cargo nextest run
• Commit messages follow Conventional Commits
• PR title and description are clear, with linked Issue
• All CI checks pass
• Responded to (or waiting for) the first round of Review

Complete Example: Fixing a Documentation Typo

The following is a complete process example from claiming to merging:

# 1. Find a good first issue on GitHub, e.g., #456: Fix typo in introduction.md
# 2. Comment on the Issue: "I'll take this task, please assign it to me."

# 3. Fork and clone (for first-time contributors)
gh repo fork Gawg-AI/EnerOS --clone
cd EnerOS
git remote add upstream https://github.com/Gawg-AI/EnerOS.git

# 4. Create a branch
git checkout main
git pull upstream main
git checkout -b docs/456-fix-typo-introduction

# 5. Modify the file
# Edit eneros-web/src/content/docs/quick-start/introduction.md, fix the typo

# 6. Check
cargo fmt --all
cargo clippy --all-targets -- -D warnings
cargo nextest run

# 7. Preview documentation locally (optional)
cd eneros-web && npm install && npm run dev

# 8. Commit
git add eneros-web/src/content/docs/quick-start/introduction.md
git commit -m "docs(quick-start): fix typo in introduction.md

- Fix 'native' mistakenly written as 'nativ'
- Add missing period

Closes #456"

# 9. Push
git push origin docs/456-fix-typo-introduction

# 10. Create a PR on the GitHub web page and fill out the template
# 11. Wait for CLA bot, CI, and Reviewer checks
# 12. After approval, the Maintainer merges and the branch is automatically deleted

Contributor Acknowledgments

All contributors with merged PRs will be automatically added to the CONTRIBUTORS.md list and acknowledged in each version’s release notes. Annual active contributors may receive:

• EnerOS Community Contributor Certificate
• Maintainer nomination eligibility
• Invitations to annual online/offline events

Related Documentation

• Development Environment Setup — Toolchain and code standards
• Testing Standards — Using cargo test and test layering
• Pull Request Process — PR process and Review standards
• Documentation Contribution Guide — Document structure and Markdown standards
• Project Structure — 56 crates and directory organization