For AI agents: the complete documentation index is available at https://docs.halo.run/llms.txt, the full documentation bundle is available at https://docs.halo.run/llms-full.txt, and this page is available as Markdown at https://docs.halo.run/guide/contribution/pr.md.
Halo 文档

    代码贡献

    欢迎关注并有想法参与 Halo 的开发，以下是关于如何参与到 Halo 项目的指南，仅供参考。

    发现 Issue

    对于新功能或较大的行为变更，请先创建 Issue 以确认范围和设计；对于目标明确的 Bug 修复，可以直接提交 Pull Request。

    寻找一个 Good First Issue

    这个步骤非常适合首次贡献者。

    在 halo-dev 和 halo-sigs 组织下，有非常多的仓库。每个仓库下都有可能包含一些“首次贡献者”友好的 Issue，主要是为了给贡献者提供一个友好的体验。该类 Issue 一般会用 good-first-issue 标签标记。标签 good-first-issue 表示该 Issue 不需要对 Halo 有深入的理解也能够参与。

    请点击：good-first-issue 查看关于 Halo 的 Good First Issue。

    认领 Issue

    若对任何一个 Issue 感兴趣，请尝试在 Issue 进行回复，讨论解决 Issue 的思路。确定后可直接通过 /assign 或者 /assign @GitHub 用户名 认领这个 Issue。这样可避免两位贡献者在同一个问题上花时间。

    代码贡献步骤

    Fork 此仓库

    点击 Halo 仓库主页右上角的 Fork 按钮即可。

    Clone 仓库到本地

    git clone https://github.com/{YOUR_USERNAME}/halo
# 或者 git clone git@github.com:{YOUR_USERNAME}/halo.git

    添加主仓库

    添加主仓库方便未来同步主仓库最新的 commits 以及创建新的分支。

    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

    创建新的开发分支

    我们需要从主仓库的主分支创建一个新的开发分支。

    git switch --create {BRANCH_NAME} upstream/main

    提交代码

    git add {CHANGED_FILES}
git commit -s -m "Fix the issue description"
git push origin {BRANCH_NAME}

    合并主分支

    在提交 Pull Request 之前，尽量保证当前分支和主分支的代码尽可能同步，这时需要我们手动操作。示例：

    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。示例：

    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 ，请确保所有代码格式化之后再提交。

    提交前请根据修改范围执行相应检查。

    后端和通用检查：

    ./gradlew spotlessApply
./gradlew spotlessCheck
./gradlew clean check

    前端检查（在仓库根目录运行）：

    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 流程创建提案并确认设计。

    AI 辅助贡献

    Halo 允许使用 AI Agent 辅助代码生成、重构和设计探索，但贡献者仍需对提交的每一行代码负责：

    • 审查并理解所有 AI 生成内容；
    • 验证正确性、安全性、性能和可维护性；
    • 删除低质量、重复或与需求无关的代码；
    • AI 对最终修改有实质贡献时，在 Pull Request 描述中说明。