贡献流程总览
欢迎为 EnerOS 贡献代码、文档或问题反馈。EnerOS 是面向电力与能源领域的原生智能体操作系统，由 56 个 Rust crate 组成，覆盖从内核到应用的完整技术栈。本页概述完整贡献流程，详细规范见后续章节。
贡献者类型
EnerOS 社区欢迎不同背景的贡献者，下表列出不同角色及其典型工作内容：
| 角色 | 典型背景 | 主要贡献 | 是否需要 CLA |
|---|---|---|---|
| 首次贡献者 | 学生、Rust 入门开发者 | 文档错别字、good first issue、补充测试 | 个人 CLA |
| 电力领域专家 | 电力系统工程师、调度员 | 算法验证、领域知识库、标准对齐 | 个人 CLA |
| Rust 开发者 | Rust 中高级开发者 | crate 实现、性能优化、Bug 修复 | 个人 CLA |
| Agent / AI 工程师 | LLM、强化学习工程师 | 推理引擎、工具链、Agent 模板 | 个人 CLA |
| 安全合规专家 | 安全研究员、合规审计员 | 安全漏洞报告、合规映射、渗透测试 | 个人 CLA |
| 文档作者 | 技术写作、翻译 | 教程、API 参考、多语言翻译 | 个人 CLA |
| Maintainer | 由社区推举产生 | Review、合并、发布、Roadmap | 个人 CLA + 维护协议 |
| 企业贡献者 | 电力企业研发团队 | 大型特性、集成方案、商业化案例 | 企业 CLA |
维护者层级
| 层级 | 权限 | 晋升路径 |
|---|---|---|
| Triager | 管理 Issue 标签与里程碑 | 持续 3 个月有效 Issue 处理 |
| Reviewer | Review 单个 crate 的 PR | 在该 crate 贡献 ≥ 10 个高质量 PR |
| Maintainer | 合并 PR、发布版本 | 担任 Reviewer ≥ 6 个月且获得 2 名 Maintainer 推荐 |
| Core Maintainer | Roadmap 决策、紧急回滚 | 担任 Maintainer ≥ 1 年且获得核心团队提名 |
贡献方式
代码贡献
代码贡献是 EnerOS 最直接的贡献方式，覆盖以下方向：
| 方向 | 相关 crate | 难度 | 入门建议 |
|---|---|---|---|
| 拓扑引擎 | eneros-topology | 中 | 实现 BFS/DFS 遍历、孤岛检测 |
| 潮流计算 | eneros-powerflow | 高 | 实现 IEEE 14-bus 测试用例 |
| 约束引擎 | eneros-constraint | 高 | 新增电压越限检查器 |
| 设备模型 | eneros-equipment | 中 | 新增变压器或线路模型 |
| 时序存储 | eneros-timeseries | 中 | 实现压缩算法或查询优化 |
| Agent 运行时 | eneros-agent | 中 | 实现 Agent 工具或生命周期钩子 |
| 协议适配 | eneros-protocol-* | 中 | 新增 IEC 104 或 Modbus 解析 |
| 安全网关 | eneros-gateway、eneros-trust | 高 | mTLS 证书轮换或 IDS 规则 |
| OS 层 | eneros-os、os/ | 高 | 内核配置或 systemd 服务 |
| 可视化 | eneros-dashboard、eneros-3d | 中 | 大屏组件或 3D 场景 |
文档贡献
文档贡献门槛低、影响面广，是首次贡献的最佳起点：
- 修正错别字、断链与格式问题
- 补充示例代码与配置片段
- 撰写新功能教程与最佳实践
- 翻译文档至英文、日文、西班牙文
详见 文档贡献规范。
测试贡献
EnerOS 拥有 7300+ 测试用例，但仍欢迎补充：
- 为未覆盖的代码路径补充单元测试
- 增加边界条件与异常场景用例
- 补充 IEEE 标准参考数据
- 撰写性能基准测试
详见 测试规范。
Issue 贡献
高质量的 Issue 是项目改进的起点：
| Issue 类型 | 模板 | 必填字段 | 奖励 |
|---|---|---|---|
| Bug 报告 | bug_report.md | 复现步骤、版本、日志 | 修复后致谢 |
| 特性请求 | feature_request.md | 场景、预期收益、替代方案 | 采纳后列入 Roadmap |
| 安全漏洞 | 私密邮件至 security@openeneros.com | 影响、复现、修复建议 | 安全致谢名单 |
| 文档问题 | doc_issue.md | 链接、原文、建议 | 直接修复 |
审查贡献
Review 是社区核心贡献形式，Reviewer 应关注：
- 正确性：算法是否符合电力领域知识？边界条件是否覆盖？
- 安全性：是否绕过约束引擎或审计链？是否引入新的明文通道？
- 性能：热路径是否引入不必要的分配？是否阻塞异步 runtime？
- 可维护性：命名是否清晰？公共 API 是否需要文档？
- 测试充分性：测试是否覆盖失败路径？是否依赖外部环境？
总体流程
Issue → Fork → 分支 → 开发与测试 → PR → Review → 合并步骤详解
1. 查找或创建 Issue
在 GitHub Issues 中确认无重复后新建。Issue 标题须简洁明确，正文按模板填写：
## 问题描述
（一段话说明遇到的问题或期望的能力）
## 复现步骤
1. 进入 ...
2. 执行 ...
3. 观察 ...
## 预期行为
（应当发生什么）
## 实际行为
（实际发生了什么，附日志或截图）
## 环境
- EnerOS 版本：
- 操作系统：
- Rust 版本：2. Fork 与克隆
# 在 GitHub 网页上点击 Fork，然后：
git clone https://github.com/<your-account>/EnerOS.git
cd EnerOS
# 添加上游仓库以便后续同步
git remote add upstream https://github.com/Gawg-AI/EnerOS.git
git fetch upstream
# 验证远程配置
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. 创建分支
从最新 main 切出分支，命名遵循以下规范：
| 类型 | 前缀 | 示例 |
|---|---|---|
| 新功能 | feat/ | feat/powerflow-pv-limits |
| Bug 修复 | fix/ | fix/123-island-detection |
| 文档 | docs/ | docs/tutorial-load-flow |
| 测试 | test/ | test/constraint-edge-cases |
| 重构 | refactor/ | refactor/topology-graph |
| 性能 | perf/ | perf/timeseries-write |
# 同步上游 main
git checkout main
git pull upstream main
# 切出特性分支
git checkout -b feat/powerflow-pv-limits4. 开发与本地测试
# 编写代码后执行以下检查
cargo fmt --all
cargo clippy --all-targets -- -D warnings
cargo nextest run
cargo nextest run -p eneros-powerflow
# 如涉及公共 API 变更，验证文档可构建
cargo doc --no-deps --all-features5. 提交 PR
提交信息符合 Conventional Commits：
git add crates/eneros-powerflow/src/solver.rs crates/eneros-powerflow/tests/solver_test.rs
git commit -m "feat(powerflow): 支持 PV 母线无功上下限
- 在 PvBus 中新增 q_min/q_max 字段
- NewtonRaphsonSolver 在无功越限时自动转 PQ 节点
- 补充 5 个测试用例覆盖越限场景
Closes #123"推送至个人 fork：
git push origin feat/powerflow-pv-limits在 GitHub 网页上创建 PR，填写 PR 模板，关联 Issue。详见 Pull Request 流程。
6. 响应 Review
- 针对每条评论回复或修改，避免无视
- 大改动建议使用
git push --force-with-lease而非 merge commit，保持历史线性 - 长期未响应的 PR（>30 天）将被关闭，可随时重开
7. 合并
通过 CI 与至少一位 Reviewer 批准后由 Maintainer 合并。合并后分支由 Maintainer 删除，关联 Issue 自动关闭。
CLA 要求
贡献者须签署 Contributor License Agreement（CLA），确保 EnerOS 社区对贡献代码拥有合法的使用、修改与再许可权利。
个人 CLA
适用于个人贡献者，签署流程：
- 在 CLA 签署页面 阅读协议
- 使用 GitHub 账号登录
- 确认身份信息（姓名、邮箱与 GitHub 用户名一致）
- 在线签署，提交后立即生效
个人 CLA 关键条款：
| 条款 | 说明 |
|---|---|
| 授权范围 | 永久、全球、免费、可再许可的版权许可 |
| 专利授权 | 授予项目使用贡献者相关专利的权利 |
| 保留权利 | 贡献者保留全部所有权，可继续用于其他项目 |
| 不保证 | 贡献者不承诺代码无缺陷，EnerOS 不承担使用风险 |
| 通知义务 | 贡献者须知悉后续可能变更许可（如双许可） |
企业 CLA
适用于企业员工以公司名义贡献。需由企业法务或授权代表签署：
- 在 企业 CLA 页面 下载协议 PDF
- 由企业授权代表签字并加盖公章
- 邮寄或扫描发送至
cla@openeneros.com - 工作人员 5 个工作日内核验并登记
CLA 验证
每个 PR 提交后，CLAssistant bot 会自动检查签署状态：
- 已签署：显示 ✅，可继续 Review 流程
- 未签署：显示 ❌，并附签署链接，需在 7 天内完成签署
如对 CLA 有疑问，请邮件至 cla@openeneros.com。
行为准则
EnerOS 社区遵循 Contributor Covenant 2.1 行为准则。以下为关键条款摘要，完整文本见 CODE_OF_CONDUCT.md。
核心承诺
- 尊重：尊重所有贡献者，禁止任何形式的人身攻击、歧视或骚扰
- 聚焦技术：讨论聚焦技术问题，对事不对人
- 保密：保密客户数据与电网拓扑信息，禁止在公开渠道分享
- 包容：欢迎不同背景、不同水平的贡献者
不可接受的行为
| 行为类型 | 示例 | 处理方式 |
|---|---|---|
| 人身攻击 | 辱骂、贬低、嘲笑 | 警告 → 暂禁 → 永封 |
| 歧视言论 | 基于性别、种族、宗教、国籍的歧视 | 直接暂禁 |
| 骚扰 | 持续骚扰、性暗示、跟踪 | 直接永封 |
| 泄密 | 公开客户数据或电网拓扑 | 永封并追究法律责任 |
| 恶意破坏 | 故意引入漏洞、删除代码、推送恶意代码 | 永封并追究法律责任 |
举报渠道
如发现违反行为准则的情况，请通过以下渠道举报：
- 邮件：
conduct@openeneros.com - 私信：任何 Maintainer 的 GitHub 私信
- 紧急安全事件：
security@openeneros.com
所有举报将保密处理，举报者不会受到报复。维护委员会在 7 个工作日内回复并处理。
首次贡献指南
入门任务推荐
首次贡献者建议从以下任务入手：
| 任务类型 | 标签 | 难度 | 预计耗时 |
|---|---|---|---|
| 文档错别字 | good first issue、docs | 低 | 30 分钟 |
| 链接修复 | good first issue、docs | 低 | 30 分钟 |
| 单元测试补充 | good first issue、test | 中 | 2-4 小时 |
| 小型 Bug 修复 | good first issue、bug | 中 | 4-8 小时 |
| 文档翻译 | i18n | 中 | 4-8 小时 |
在 GitHub Issues 页面筛选 good first issue 标签即可看到推荐任务。
首次贡献检查清单
- 已阅读本页”总体流程”与”行为准则”章节
- 已签署个人 CLA
- 已 Fork 仓库并完成本地构建
- 已选择一个
good first issue任务并在 Issue 下留言认领 - 已创建符合命名规范的分支
- 已通过
cargo fmt、cargo clippy、cargo nextest run - 提交信息符合 Conventional Commits 规范
- PR 标题与描述清晰，关联了 Issue
- CI 全部通过
- 已响应（或等待）首轮 Review
完整示例：修复文档错别字
以下是从认领到合并的完整流程示例：
# 1. 在 GitHub 上找到 good first issue，例如 #456：修复 introduction.md 错别字
# 2. 在 Issue 下留言："我来处理这个任务，请分配给我。"
# 3. Fork 并克隆（首次贡献者）
gh repo fork Gawg-AI/EnerOS --clone
cd EnerOS
git remote add upstream https://github.com/Gawg-AI/EnerOS.git
# 4. 创建分支
git checkout main
git pull upstream main
git checkout -b docs/456-fix-typo-introduction
# 5. 修改文件
# 编辑 eneros-web/src/content/docs/quick-start/introduction.md，修正错别字
# 6. 检查
cargo fmt --all
cargo clippy --all-targets -- -D warnings
cargo nextest run
# 7. 本地预览文档（可选）
cd eneros-web && npm install && npm run dev
# 8. 提交
git add eneros-web/src/content/docs/quick-start/introduction.md
git commit -m "docs(quick-start): 修正 introduction.md 中的错别字
- 将'原生'误写为'原身'修正
- 补充缺失的句号
Closes #456"
# 9. 推送
git push origin docs/456-fix-typo-introduction
# 10. 在 GitHub 网页上创建 PR，填写模板
# 11. 等待 CLA bot、CI、Reviewer 检查
# 12. 通过后由 Maintainer 合并，分支自动删除贡献者致谢
所有被合并 PR 的贡献者将自动加入 CONTRIBUTORS.md 名单，并在每个版本发布说明中致谢。年度活跃贡献者可获得：
- EnerOS 社区贡献者证书
- Maintainer 提名资格
- 年度线上/线下活动邀请
相关文档
- 开发环境搭建 — 工具链与代码规范
- 测试规范 —
cargo test使用与测试分层 - Pull Request 流程 — PR 流程与 Review 标准
- 文档贡献规范 — 文档结构与 Markdown 规范
- 项目结构 — 56 个 crate 与目录组织