贡献指南 | 参与 Harmonybrew 开源社区共建规范
贡献指南 | 参与 Harmonybrew 开源社区共建规范
欢迎大家加入鸿蒙PC社区
Harmonybrew 是面向 OpenHarmony/鸿蒙系统的 Homebrew 移植开源项目，依托多仓库协作模式，实现包管理器适配、软件包移植、工具适配、文档维护等全链路能力。为规范社区贡献流程、统一协作标准、提升共建效率，本文将详细说明各仓库差异化贡献规则、新手友好贡献方向，帮助开发者快速上手社区共建。
本项目仓库分为上游 Fork 仓库与项目自研新建仓库两大类，两类仓库的定位、迭代逻辑、贡献规范差异较大，所有社区贡献者需严格遵循对应仓库的贡献规则，保证项目迭代的规范性与稳定性。
一、各仓库核心信息与贡献规则
Harmonybrew 项目依托多个独立仓库承载不同业务能力，各仓库的来源、用途、维护主体各不相同，对应的 PR 提交、代码规范、审核标准也存在差异化要求。以下为全仓库详细贡献规范汇总：
| 仓库链接 | 核心内容 | 仓库来源 | 项目用途 | 详细贡献规则 |
|---|---|---|---|---|
| brew | Homebrew 客户端源码 | 上游官方仓库 Fork | 承载鸿蒙版 Homebrew 包管理器核心能力，是用户终端直接调用的核心程序，所有鸿蒙设备的包管理核心逻辑均来自此仓库。 | 1. 代码注释、Git 提交信息统一使用英文，提交规范完全对齐上游 Homebrew 标准；2. PR 描述、问题说明可使用中文，方便社区审阅交流；3. 严格控制代码修改范围，仅保留鸿蒙适配必要改动，禁止个人偏好修改、企业定制化改造，禁止无意义的上游代码“优化”。 |
| install | Homebrew 安装/卸载脚本 | 上游官方仓库 Fork | 提供鸿蒙系统专属的一键安装、卸载脚本，是用户部署 Harmonybrew 的唯一入口。 | 1. 脚本注释、Git 提交信息统一使用英文，完全遵循上游提交规范；2. PR 描述支持中文说明；3. 仅维护鸿蒙适配所需的兼容性修改，拒绝个性化、定制化改动，不做冗余功能优化。 |
| homebrew-core | 软件包 Formula 源码仓库 | 以上游 Fork 为基础，批量搬运、适配开源软件包 | 项目核心软件包仓库，用户通过brew install安装的所有开源软件，均由此仓库的 Formula 脚本编译构建生成。 | 专属规范，详见官方文档：如何贡献 formula，所有软件包适配、新增、修改均需遵循该文档标准。 |
| ci | 项目流水线脚本 | 项目自研新建 | 适配 CodeArts Pipeline 流水线平台，自研实现项目构建、编译、测试、发布全流程自动化逻辑，无法复用上游 GitHub Action 流水线。 | 由 Harmonybrew 官方维护团队专属迭代维护，暂不接纳外部 PR 贡献，外部开发者无需提交代码修改。 |
| docs | 项目官方文档 | 项目自研新建 | 承载项目安装指南、使用教程、贡献规范、问题排查等全量官方文档，是社区用户、开发者的核心参考资料。 | 1. 文档注释、Git 提交信息统一使用中文；2. 文档审核标准严格，所有修改需具备明确的社区价值、实用性与必要性，无意义的文案微调、冗余修改大概率会被拒收。 |
| pages | 项目官方主页 | 项目自研新建 | 静态网页资源，部署对外官方站点 https://harmonybrew.atomgit.com，展示项目介绍、设备支持、快速入门等内容。 | 页面代码注释、Git 提交信息统一使用中文，遵循前端轻量化维护规范。 |
| .gitcode | 组织全局配置 | 项目自研新建 | 仅存储社区组织级 Issue 模板，用于统一问题反馈格式，无其他业务配置能力。 | 由官方维护团队统一管理，暂不接纳外部 PR 贡献。 |
| formula-migration-tool | Formula 自动化搬运工具 | 项目自研新建 | 自研自动化工具，用于批量搬运、适配、校验上游开源软件包，提升 Formula 移植效率。 | 代码注释、Git 提交信息统一使用中文，适配鸿蒙移植场景自主迭代。 |
| uname-is-linux | 系统标识伪装工具 | 项目自研新建 | 鸿蒙 PC 专属适配工具，解决开源软件无法识别 HarmonyOS 系统标识的编译报错问题。 | 代码注释、Git 提交信息统一使用中文，面向鸿蒙适配场景迭代优化。 |
| ohos-pip-autosign | Python 三方库自动签名工具 | 项目自研新建 | 解决鸿蒙系统 Python 扩展库 .so 文件未签名、无法加载的核心痛点，完善 Python 开发生态。 | 代码注释、Git 提交信息统一使用中文，聚焦鸿蒙 Python 生态适配优化。 |
| custom-tap-example | 自定义 Tap 样例项目 | 项目自研新建 | 提供开源可参考的自定义 Tap 开发样例，支撑官方教程文档落地，供开发者学习参考。 | 由官方维护团队统一维护更新，暂不接纳外部 PR 贡献。 |
| ohos-xxx 系列仓库 | 鸿蒙移植开源软件合集 | 项目自研新建 | 托管于 GitHub 平台，依托 GitHub 流水线构建，作为项目基础设施支撑内部适配工作，开源对外开放使用。 | 由官方维护团队专属迭代维护，暂不接纳外部 PR 贡献。 |
二、新手友好：急需社区共建的核心方向
Harmonybrew 维护团队人力有限，项目存在大量可优化、待完善的场景。如果你是开源新手，想要参与社区贡献但暂无明确切入点，可优先选择以下低门槛、高价值的共建方向，所有贡献均会被社区记录与认可。
2.1 文档国际化建设
当前项目官方文档仅提供中文版本，缺乏配套英文文档，无法与上游 Homebrew 社区、海外开源开发者完成高效交流。亟需熟悉 Homebrew 使用规范、具备基础英文读写能力的开发者，协助完成文档国际化翻译、校对、适配工作，打通内外社区沟通壁垒。
2.2 开源软件包适配移植
目前上游 Homebrew 海量 Formula 软件包，仅有少量完成鸿蒙平台适配并录入homebrew-core仓库。大量常用开源工具、开发库仍无法在鸿蒙设备上直接安装使用。欢迎具备 C/C++、Python 编译适配、跨平台移植能力的开发者，参与上游软件包的鸿蒙适配、补丁开发、脚本优化工作，持续丰富鸿蒙开源生态。
2.3 软件包兼容性实测校验
当前仓库内所有适配完成的软件包，仅在流水线中完成基础brew test冒烟测试，未经过多设备、多场景的充分实测，大量软件包在真实鸿蒙设备（鸿蒙 PC、开发板、容器）上的兼容性、可用性未知。
开发者可优先参考项目下载数据统计页面，针对下载量高、社区使用率大的热门软件包，在不同鸿蒙设备上进行功能实测、场景验证，将发现的兼容问题、功能 bug 提交至仓库 Issue，协助团队迭代优化。
2.4 AI 辅助适配工作流建设
现阶段项目 Formula 移植、软件适配工作高度依赖开发者个人经验，AI 辅助能力碎片化、无统一规范，未形成标准化、可复用的工作流程。
欢迎熟悉 AI 工程化、自动化脚本开发的开发者，共建社区 AI 辅助体系：沉淀通用适配 Prompt、开发自动化移植 Agent 脚本、搭建标准化 AI 辅助工作流，降低新手移植门槛，大幅提升软件包适配效率。
2.5 社区 Issue 认领修复
社区所有问题统一汇总至 社区 Issue 中心，其中homebrew-core 仓库相关 Issue是社区重点攻坚方向，维护团队精力有限，基本依赖社区开发者互帮互助解决。新手可优先认领简单问题（适配报错、安装异常、文档瑕疵等），快速参与社区共建。
三、贡献通用准则
- 合规优先：所有贡献需符合各仓库专属规范，Fork 仓库严格对齐上游标准，自研仓库遵循中文协作规范；
- 价值优先：所有 PR、Issue、文档修改需具备实际社区价值，拒绝无意义微调、灌水式贡献；
- 克制修改：上游 Fork 仓库仅做必要适配修改，杜绝个性化、企业化定制改造，保证项目通用性；
- 积极反馈：参与测试、适配、优化后，及时通过 Issue、PR 沉淀成果，助力项目持续迭代。