Repository navigation
Align contribution docs with the maintainer-only PR policy #629
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Merged
Merged
Changes from all commits
Commits
File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,5 +1,5 @@ | ||
| --- | ||
| title: 参与贡献 | ||
| description: 参与 Halo 开源项目的完整指南,涵盖通过 GitHub 提交问题反馈、寻找适合的 Issue、编写代码并发起 Pull Request 的流程与规范。 | ||
| description: 了解 Halo 的问题反馈渠道与贡献政策,通过 Bug 反馈、功能建议和社区讨论参与项目建设。 | ||
| overview: true | ||
| --- |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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。这样可避免两位贡献者在同一个问题上花时间。 | ||
|
|
||
| ## 代码贡献步骤 | ||
|
|
||
| <Steps> | ||
|
|
||
| ### Fork 此仓库 | ||
|
|
||
| 点击 Halo 仓库主页右上角的 `Fork` 按钮即可。 | ||
|
|
||
| ### Clone 仓库到本地 | ||
|
|
||
| ```bash | ||
| git clone https://github.com/{YOUR_USERNAME}/halo | ||
| # 或者 git clone [email protected]:{YOUR_USERNAME}/halo.git | ||
| ``` | ||
|
|
||
| ### 添加主仓库 | ||
|
|
||
| 添加主仓库方便未来同步主仓库最新的 commits 以及创建新的分支。 | ||
|
|
||
| ```bash | ||
| git remote add upstream https://github.com/halo-dev/halo.git | ||
| # 或者 git remote add upstream [email protected]: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} | ||
| ``` | ||
|
|
||
| </Steps> | ||
|
|
||
| ## 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` 主仓库。文档、插件、主题及其他生态项目的贡献方式,请以各自仓库的贡献指南为准。 | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.