Ant Design Blazor 贡献指南全解读：从 Issue 提交到 Commit Message 规范的完整贡献流程

本文以仓库根目录 CONTRIBUTING.md 为骨架，结合 docs/contributing.zh-CN.md 与仓库内测试、脚本、变更日志等真实实现，系统性讲解如何为 Ant Design Blazor 提交高质量的 Issue 与 Pull Request。读完本文，你将掌握：项目要求的 Issue 最小复现规范、PR 从建分支到合入后的完整操作流程、必须遵循的编码规则，以及驱动自动生成变更日志的 Commit Message 格式约定（type / scope / subject / body / footer）。

一、贡献方式总览：你可以从哪些渠道参与

Ant Design Blazor 欢迎一切形式的贡献，官方支持三种参与方式：

1. 报告问题（Issue）：发现源码中的 bug 时提交 Issue；
2. 参与讨论：在已有 Issue 下留言补充信息、讨论方案；
3. 提交 Pull Request：直接提交修复代码或新功能实现。

同时，文档明确划定了渠道边界：一般性的技术咨询不要开 Issue。GitHub Issues 只保留给 bug 报告和功能请求，答疑类问题应优先在 Segmentfault / Stack Overflow 上以 ant-design-blazor 标签提问（对应社区渠道的说明见 docs/faq.zh-CN.md 等文档入口）。项目方会系统性地关闭所有"一般支持类"Issue，并引导提问者去问答社区，这是为了确保 Issue 列表始终聚焦、可检索。如需实时交流，可加入项目 Discord 社区。

二、提交 Issue 的规范：最小复现是硬性要求

2.1 提交前的必要动作

在提交 Issue 之前，请先搜索已有的 Issue 列表，因为大概率已经存在同类问题，已有的讨论可能直接给出可行的 workaround，也能避免重复劳动。报告中请说明：

• 使用的 ant-design-blazor 版本；
• 相关第三方库及其版本；
• 最关键的部分——一个失败的使用场景（use-case）。

2.2 为什么强调"最小复现"

项目方的立场是：没有最小复现，就无法定位和修复 bug。文档中明确了两点：

• 维护者会系统性要求提交者提供一个基于 http://plnkr.co 的最小可复现场景（minimal reproduction scenario）；
• 如果无法通过 plunker 演示（例如与 npm 打包相关的问题），则要求提供一个独立的 git 仓库来演示问题。

这一要求并不是刁难，而是有实际收益的：在准备最小复现样例的过程中，提交者往往自己就发现了编码问题。即便不能，隔离出最小问题域也能让维护者免去反复追问（版本、第三方库、失败场景）的来回沟通成本，从而更快确认 bug、更快修复。对于信息不足以复现的 Issue，项目会在无法获得反馈后直接关闭。

三、功能请求与 Feature 提交策略

如果你希望改进 API 或新增功能，需先提交功能请求 Issue。文档给出了一个重要决策规则，按改动规模分两条路径：

改动规模	正确路径	原因
Major Feature（大型功能）	先开 Issue，说明方案和使用场景（usage scene）	让方案先被讨论，便于协调人力、避免重复开发、提高合入成功率
Small Feature（小型功能）	直接编写代码并提交 Pull Request	改动小、边界清晰，可以走快速通道

注意：即便是"直接提交 PR"的小功能，也建议先有 Issue 或清晰的讨论上下文，方便评审者理解意图。

四、提交 Pull Request 的完整流程

4.1 提交前的准备清单

按照 CONTRIBUTING.md 与 docs/contributing.zh-CN.md 的要求，发送 PR 前必须逐项确认：

1. 先搜索 GitHub 上已打开或已关闭的 PR，避免重复工作；
2. 在 master 基础上新建独立分支；
3. 编写补丁，必须包含合适的测试用例；
4. 遵循项目编码规则（见下文第五节）；
5. 运行完整测试套件，确保全部通过；
6. 用符合规范的 Commit Message 提交（见下文第六节）；
7. 提交前完成正确的 Rebase。

4.2 分支与提交操作

# 1. 从 master 新建修复分支
git checkout -b my-fix-branch master

# 2. 创建补丁（含测试用例）并提交
git commit -a

其中 git commit -a 是官方推荐的提交方式：该参数会自动对已编辑的文件执行 "add" 和 "rm"，避免漏加文件。

4.3 推送与发起 PR

# 推送到你的远程仓库
git push origin my-fix-branch

然后到 GitHub 上向 ant-design-blazor:master 发起 Pull Request。评审过程中如果维护者要求修改：

# 修改后重新跑完整测试套件
# 接着交互式变基并强制推送以更新 PR
git rebase master -i
git push -f

git rebase master -i 用于在推送前整理提交历史，git push -f 更新已存在的 PR 分支。这也是中文版贡献指南中强调的"提交之前进行正确的 Rebase"。

4.4 PR 合入后的清理流程

PR 被合并后，可以安全地清理本地与远端分支：

# 删除远端分支（也可通过 GitHub Web UI 操作）
git push origin --delete my-fix-branch

# 切回 master 并删除本地分支
git checkout master -f
git branch -D my-fix-branch

# 同步上游最新代码（fast-forward）
git pull --ff upstream master

如果尚未配置 upstream，可先执行 git remote add upstream <仓库地址>，并定期用 git pull upstream master 同步（具体步骤见 docs/contributing.zh-CN.md）。

五、编码规则（Coding Rules）

为保证全仓库代码风格一致，CONTRIBUTING.md 提出两条硬性规则：

1. 所有功能或 bug 修复都必须有对应的测试（unit-tests / specs）；
2. 所有公共 API 方法必须有文档注释。

这两条规则在仓库中有着充分的实现佐证：

• 测试工程 tests/AntDesign.Tests/AntDesign.Tests.csproj 以组件为维度组织测试目录，覆盖 Alert、AutoComplete、Avatar、Badge、Breadcrumb、Button、Card、Cascader、Checkbox、DatePicker、Dropdown、Form、Menu、Select、Slider、Steps、Table、Tabs、Tree、Upload 等几乎所有组件，并引用 tests/AntDesign.TestKit 提供的 AntDesignTestBase 基类与测试 DOM 事件服务，用于组件级单元测试；
• 测试工程同时使用 xUnit 与 FluentAssertions，多目标框架为 net5;net6;net8;net9;net10.0，可见项目对跨 .NET 版本兼容性的测试要求；
• JS 侧代码（components 下的 *.ts）则通过 npm run lint（eslint）与 npm run lint-fix 进行风格检查，相关脚本定义在 package.json。

六、Commit Message 规范：驱动自动生成变更日志的格式约定

6.1 为什么要规范 Commit Message

这是整个贡献流程中最值得深入理解的部分。CONTRIBUTING.md 明确指出：

• 规范的提交信息让项目历史更易阅读、更易追溯；
• 项目直接使用 git commit message 来自动生成变更日志（change log），因此提交信息的质量直接决定发布说明的质量。

仓库中的 scripts/print-changelog.js 就是这一机制的实现：脚本通过 simple-git 读取指定 tag 区间内的提交记录，从提交信息中正则匹配 #\d+ 提取关联 PR 编号，再抓取 PR 元数据，最终按「中文 / 英文」两栏生成发布说明（npm run changelog，定义于 package.json）。也就是说，一条不规范的 commit 会直接污染自动生成的变更日志。同时，CHANGELOG.zh-CN.md 显示项目严格遵循 Semantic Versioning 2.0.0，发布节奏为：修订版本号每周日常 bugfix、次版本号每月向下兼容新特性、主版本号按需发布破坏性更新——这进一步说明 fix: / feat: 等 type 前缀与版本号语义存在强对应关系。

6.2 Commit Message 的完整格式

每条提交信息由 header（头部）、body（正文）、footer（页脚） 三部分组成，其中 header 必须存在，scope 可选：

<type>(<scope>): <subject>
<空行>
<body>
<空行>
<footer>

任何一行的长度都不能超过 100 个字符，以保证在 GitHub 及各种 git 工具中的可读性。

6.3 Header：type / scope / subject

**type（必填）**必须是以下取值之一，这是全项目统一的受控词表：

type	含义	示例场景
build	影响构建系统或外部依赖的改动	gulp、npm 相关配置
ci	修改 CI 配置文件与脚本	Travis、Circle、SauceLabs 等
docs	仅文档改动	更新文档、修正错别字
feat	新功能	新增组件属性
fix	bug 修复	修复组件异常
perf	提升性能的代码改动	优化渲染逻辑
refactor	既非修复 bug 也非新增功能的代码重构	结构调整
style	不影响代码含义的改动	空白、格式、缺失分号
test	补充或修正测试	新增测试用例

**scope（可选）**必须是受影响模块的名称（文件夹名或其他有意义的名字），并带 module: 前缀，例如：

• module:alert
• module:badge
• module:breadcrumb
• module:OTHER_COMPONENT_NAME

从仓库结构看，组件目录正是以这些模块名组织的（如 components/alert、components/badge、components/breadcrumb），scope 直接对应用户感知的组件名，方便从变更日志快速定位影响面。

scope 目前有几个例外，不强制使用模块名：

例外 scope	适用场景
packaging	改变 npm 包布局的改动，如 public path、package.json、d.ts 格式、bundle 等
changelog	更新 CHANGELOG 发布说明
showcase	与站点展示（docs-app）相关的改动
空字符串	适合跨全包的 style、test、refactor 改动，例如 style: add missing semicolons

**subject（必填）**是简短变更描述，三条硬规则：

1. 使用祈使句、现在时：写 "change"，不要写 "changed" 或 "changes"；
2. 首字母不要大写；
3. 结尾不要句号（.）。

官方示例：

docs(changelog): update change log to beta.5

fix(release): need to depend on latest rxjs and zone.js

The version in our package.json gets copied to the one we publish, and users need the latest of these.

6.4 Body：动机与行为对比

body 与 subject 一样使用祈使句、现在时，其职责是说明这次改动的动机（motivation），并与之前的旧行为做对比。上面第二条示例就是一个标准示范：header 交代修复内容，body 解释"package.json 中的版本会被复制到发布产物、用户需要这些最新依赖"这一深层原因。

6.5 Footer：Breaking Changes 与 Issue 关联

footer 承载两类信息：

1. Breaking Changes（破坏性变更）：必须以 BREAKING CHANGE: 开头，后跟一个空格或换行；
2. Issue 关闭引用：引用本次提交关闭的 GitHub Issue，格式遵循 GitHub 的 closing reference 语法。

6.6 Revert 提交的特殊格式

如果某次提交是回滚（revert）之前的提交，必须以 revert: 开头，后跟被回滚提交的 header；正文中必须写明 This reverts commit <hash>.，其中 <hash> 是被回滚提交的 SHA。

七、本地开发与测试验证：贡献前的自检闭环

合入 PR 前，完整的本地验证闭环是必备环节。中文版指南给出四个高频命令：

命令	用途
dotnet run	本地运行 ant-design-blazor 的文档站点
dotnet build	编译解决方案并检查代码风格
dotnet test	运行全部测试
dotnet publish -c release -o publish	构建发布产物到 publish 目录

对于测试，仓库还提供了面向 CI 稳定性的脚本 tests/run-tests.ps1，支持多次运行、指定 Release/Debug 配置与目标框架，并通过 --blame-hang --blame-hang-timeout 100s 定位挂起用例，例如：

# 以 Release 配置、默认 dotnet 版本运行 1 次
.\run-tests.ps1 1 Release

# 以 Release 配置、net8 框架运行 5 次
.\run-tests.ps1 5 Release net8

如果你的改动同时涉及 JS 侧代码，还需保证 npm run lint（eslint 检查 components 下 *.ts 文件）通过。全部验证通过后，再按照第六节的格式提交，即可发起 PR，等待团队 review。

八、总结：让每一份贡献都能被高效吸收

Ant Design Blazor 的贡献流程可以归纳为一条清晰的链路：Issues 只留给 bug 与功能请求 → 提交必须带最小复现 → PR 必须含测试且通过全量验证 → Commit Message 严格遵循 type/scope/subject/body/footer 格式 → 规范提交自动驱动变更日志与版本发布。其中 Commit Message 规范是整个机制的技术核心——它与 scripts/print-changelog.js、CHANGELOG.zh-CN.md 的自动生成流程直接挂钩，理解这一点，你就理解了为什么项目对提交信息如此"苛刻"。按此规范行事，你的 Issue 与 PR 将更快被确认、评审与合入。