diff --git a/docs/guide/contribution/index.md b/docs/guide/contribution/index.md index ff8eda0b..ed29f8af 100644 --- a/docs/guide/contribution/index.md +++ b/docs/guide/contribution/index.md @@ -1,5 +1,5 @@ --- title: 参与贡献 -description: 参与 Halo 开源项目的完整指南，涵盖通过 GitHub 提交问题反馈、寻找适合的 Issue、编写代码并发起 Pull Request 的流程与规范。 +description: 了解 Halo 的问题反馈渠道与贡献政策，通过 Bug 反馈、功能建议和社区讨论参与项目建设。 overview: true --- diff --git a/docs/guide/contribution/issue.md b/docs/guide/contribution/issue.md index 76f6581f..da5a3466 100644 --- a/docs/guide/contribution/issue.md +++ b/docs/guide/contribution/issue.md @@ -9,7 +9,8 @@ description: 通过 GitHub Issue、Discussion 或 Halo 官方社区反馈使用 ## GitHub -- [https://github.com/halo-dev/halo/issues](https://github.com/halo-dev/halo/issues) +- [https://github.com/halo-dev/halo/issues](https://github.com/halo-dev/halo/issues)：反馈 Halo 核心项目的 Bug 或提出功能建议，请提供复现步骤或清晰的需求描述。 +- [https://github.com/halo-dev/halo/discussions](https://github.com/halo-dev/halo/discussions)：交流使用、部署等问题。 - [https://github.com/orgs/lxware-dev/discussions](https://github.com/orgs/lxware-dev/discussions)：Halo 付费版或者付费应用的问题可以在这里进行反馈。 如果你在使用过程中，遇到了一些 bug 或者需要添加某些新特性，请尽量在 GitHub 进行反馈，这非常有助于我们跟踪解决此问题，您也可以很方便的接收到处理状态。 diff --git a/docs/guide/contribution/pr.mdx b/docs/guide/contribution/pr.mdx index dfc1b942..c78c744f 100644 --- a/docs/guide/contribution/pr.mdx +++ b/docs/guide/contribution/pr.mdx @@ -1,147 +1,25 @@ --- -title: 代码贡献 -description: 参与 Halo 代码贡献的完整流程，涵盖查找并认领 Good First Issue、Fork 与同步仓库、创建分支、提交代码、发起及更新 Pull Request。 +title: 贡献政策 +description: 了解 Halo 主仓库的贡献政策：Pull Request 仅限项目维护者提交，外部用户仍可通过问题反馈、功能建议和社区讨论参与项目建设。 --- -import { Steps } from "@rspress/core/theme"; +## 主仓库贡献政策 -欢迎关注并有想法参与 Halo 的开发，以下是关于如何参与到 Halo 项目的指南，仅供参考。 +[Halo 主仓库](https://github.com/halo-dev/halo)目前仅接受项目维护者提交的 Pull Request，暂不接受外部贡献者的 Pull Request，包括代码、测试和文档修改。 -## 发现 Issue +欢迎通过 Issue 反馈 Bug、提出功能建议，或通过 Discussions 参与讨论。创建 Issue 或参与讨论不代表获得提交 Pull Request 的许可。 -对于新功能或较大的行为变更，请先创建 Issue 以确认范围和设计；对于目标明确的 Bug 修复，可以直接提交 Pull Request。 +## 反馈与讨论 -### 寻找一个 Good First Issue +- [GitHub Issues](https://github.com/halo-dev/halo/issues)：反馈 Halo 核心项目的 Bug 或提出功能建议，请提供复现步骤或清晰的需求描述。 +- [GitHub Discussions](https://github.com/halo-dev/halo/discussions)：交流使用、部署等问题。 -> 这个步骤非常适合首次贡献者。 +更多反馈渠道和提交建议，请参阅[问题反馈](./issue.md)。 -在 [halo-dev](https://github.com/halo-dev) 和 [halo-sigs](https://github.com/halo-sigs) 组织下，有非常多的仓库。每个仓库下都有可能包含一些“首次贡献者”友好的 Issue，主要是为了给贡献者提供一个友好的体验。该类 Issue -一般会用 `good-first-issue` 标签标记。标签 `good-first-issue` 表示该 Issue 不需要对 Halo 有深入的理解也能够参与。 +## 维护者开发流程 -请点击：[good-first-issue](https://github.com/issues?q=org%3Ahalo-dev+is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22+no%3Aassignee+) -查看关于 Halo 的 Good First Issue。 +项目维护者请参阅主仓库的 [Contributing Guide](https://github.com/halo-dev/halo/blob/main/CONTRIBUTING.md)，了解开发环境、提交前检查、Pull Request 流程以及 AI 辅助开发等要求。 -### 认领 Issue +## 其他仓库 -若对任何一个 Issue 感兴趣，请尝试在 Issue 进行回复，讨论解决 Issue 的思路。确定后可直接通过 `/assign` 或者 `/assign @GitHub 用户名` 认领这个 -Issue。这样可避免两位贡献者在同一个问题上花时间。 - -## 代码贡献步骤 - - - -### Fork 此仓库 - -点击 Halo 仓库主页右上角的 `Fork` 按钮即可。 - -### Clone 仓库到本地 - -```bash -git clone https://github.com/{YOUR_USERNAME}/halo -# 或者 git clone git@github.com:{YOUR_USERNAME}/halo.git -``` - -### 添加主仓库 - -添加主仓库方便未来同步主仓库最新的 commits 以及创建新的分支。 - -```bash -git remote add upstream https://github.com/halo-dev/halo.git -# 或者 git remote add upstream git@github.com:halo-dev/halo.git -git fetch upstream main -``` - -### 创建新的开发分支 - -我们需要从主仓库的主分支创建一个新的开发分支。 - -```bash -git switch --create {BRANCH_NAME} upstream/main -``` - -### 提交代码 - -```bash -git add {CHANGED_FILES} -git commit -s -m "Fix the issue description" -git push origin {BRANCH_NAME} -``` - -### 合并主分支 - -在提交 Pull Request 之前，尽量保证当前分支和主分支的代码尽可能同步，这时需要我们手动操作。示例： - -```bash -git fetch upstream -git merge upstream/main -git push origin {BRANCH_NAME} -``` - - - -## Pull Request - -进入此阶段说明已经完成了代码的编写，测试和自测，并且准备好接受 Code Review。 - -### 创建 Pull Request - -回到自己的仓库页面，选择 `New pull request` 按钮，创建 `Pull request` 到原仓库的 `main` 分支。 -然后等待我们 Review 即可，如有 `Change Request`，再本地修改之后再次提交即可。 - -提交 Pull Request 的注意事项： - -- 提交 Pull Request 请充分自测。 -- 每个 Pull Request 尽量只解决一个 Issue，特殊情况除外。 -- 应尽可能多的添加单元测试，其他测试（集成测试和 E2E 测试）可看情况添加。 -- Pull Request 默认提交到主仓库的 `main` 分支，由维护者决定是否需要应用到维护分支。 -- 按照 Pull Request 模板填写变更原因、关联 Issue、Release Note（没有用户可见变更时填写 `NONE`）和 `/kind` 标签。 - -### 更新 commits - -Code Review 阶段可能需要 Pull Request 作者重新修改代码，请直接在当前分支 commit 并 push 即可，无需关闭并重新提交 Pull Request。示例： - -```bash -git add {CHANGED_FILES} -git commit -s -m "Address review feedback" -git push origin bug/king -``` - -同时，若已经进入 Code Review 阶段，请不要强制推送 commits 到当前分支。否则 Reviewers 需要从头开始 Code Review。 - -### 开发规范 - -请参考 [https://docs.halo.run/developer-guide/core/code-style](https://docs.halo.run/developer-guide/core/code-style) -，请确保所有代码格式化之后再提交。 - -提交前请根据修改范围执行相应检查。 - -后端和通用检查： - -```bash -./gradlew spotlessApply -./gradlew spotlessCheck -./gradlew clean check -``` - -前端检查（在仓库根目录运行）： - -```bash -pnpm -C ui install -pnpm -C ui build:packages -pnpm -C ui lint -pnpm -C ui typecheck -pnpm -C ui test:unit -``` - -### 功能和 API 变更 - -功能变更或 API 变更（新增端点、破坏性变更、行为调整）需要在实现前按照 [OpenSpec](https://github.com/Fission-AI/OpenSpec) 流程创建提案并确认设计。 - -### AI 辅助贡献 - -Halo 允许使用 AI Agent 辅助代码生成、重构和设计探索，但贡献者仍需对提交的每一行代码负责： - -- 审查并理解所有 AI 生成内容； -- 验证正确性、安全性、性能和可维护性； -- 删除低质量、重复或与需求无关的代码； -- AI 对最终修改有实质贡献时，在 Pull Request 描述中说明。 +以上 Pull Request 限制适用于 `halo-dev/halo` 主仓库。文档、插件、主题及其他生态项目的贡献方式，请以各自仓库的贡献指南为准。 diff --git a/docs/guide/prepare.md b/docs/guide/prepare.md index 5ebaaf5e..1cc250fd 100644 --- a/docs/guide/prepare.md +++ b/docs/guide/prepare.md @@ -194,7 +194,7 @@ Halo 使用 [GPL-3.0](https://github.com/halo-dev/halo/blob/main/LICENSE) 协议 ## 贡献者 -欢迎参与 Halo 项目建设，具体方式请参阅 [Halo 贡献指南](https://github.com/halo-dev/halo/blob/main/CONTRIBUTING.md)。 +欢迎通过 Bug 反馈、功能建议和社区讨论参与 Halo 项目建设，具体方式请参阅[问题反馈](./contribution/issue.md)与[贡献政策](./contribution/pr.mdx)。 Halo 项目贡献者