This is the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

SDK 贡献指南

如何为 Dapr SDK 文档做出贡献

1: 为 .NET SDK 做贡献
2: 为 Go SDK 做贡献
3: 为 Java SDK 贡献
4: 为 JavaScript SDK 做出贡献
5: 为 Python SDK 贡献
6: 为 Rust SDK 做贡献

1 - 为 .NET SDK 做贡献

为 Dapr .NET SDK 做贡献的指南

欢迎！

如果您正在阅读本文，您可能有兴趣为 Dapr 和/或 Dapr .NET SDK 做贡献。欢迎加入本项目，感谢您对贡献的兴趣！

请查阅相关文档，熟悉 Dapr 是什么以及它要实现的目标，并通过 Discord 与我们联系。请告诉我们您希望如何贡献，我们很乐意提供想法和建议。

为 Dapr 做贡献有多种方式：

为 Dapr runtime 或 Dapr .NET SDK 提交错误报告
提出新的 runtime 能力或 SDK 功能
改进 Dapr 主项目或 Dapr .NET SDK 专属的文档
为实现各种构建块的组件新增或改进现有组件
增强 .NET 可插拔组件 SDK 能力
改进 Dapr .NET SDK 代码库和/或修复 bug（详见下文）

如果您是代码库的新手，请随时在 Discord 的 #dotnet-sdk 频道询问如何实现更改或提出一般性问题。您不需要获得许可即可处理任何问题，但请注意，如果某个问题已分配给某人，这表明可能有人已开始处理该问题。特别是如果该问题已有一段时间没有活动，请随时联系，确认他们是否仍有兴趣继续，或者您是否可以接手，并使用您的实现打开一个拉取请求。

如果您想将自己分配给某个问题，请使用 “/assign” 回复对话，机器人会将您分配给它。

我们已将一些问题标记为 good-first-issue 或 help wanted，表明这些可能是小型的、自包含的更改。

如果您对实现不确定，请将其创建为草稿拉取请求，并通过标记 @dapr/maintainers-dotnet-sdk 并提供一些您需要帮助的上下文来征求 .NET 维护者的反馈。

贡献规则和最佳实践

为 .NET SDK 做贡献时，应遵循以下规则和最佳实践。

拉取请求

通常不鼓励仅包含格式更改的拉取请求。拉取请求应旨在修复 bug、添加新功能或改进现有功能。

请尽量将拉取请求的内容最小化，使其仅涵盖单个问题。涉及大量文件的大型 PR 不太可能在短时间内被审查或接受。在单个 PR 中处理许多不同问题使得难以确定您的代码是否完全解决了潜在问题，并使代码审查变得复杂。

测试

所有拉取请求都应包含单元测试和/或集成测试，以反映添加或更改内容的性质，以便清楚地表明功能按预期工作。避免使用自动生成的测试来多次重复测试相同的功能。相反，应通过验证更改的每个可能路径来提高代码覆盖率，以便未来的贡献者可以更容易地理解您逻辑的轮廓并更容易地识别局限性。

示例

examples 目录包含代码示例，供用户运行以尝试各种 Dapr .NET SDK 包和扩展的特定功能。在编写和更新示例时，请记住：

所有示例都应能够在 Windows、Linux 和 MacOS 上运行。虽然 .NET Core 代码在操作系统之间保持一致，但任何示例前/后命令都应通过 tabpane 提供选项
包含下载/安装任何所需先决条件的步骤。对于全新操作系统安装的人来说，应该能够从示例开始并完成而不会出错。指向外部下载页面的链接是可以的。

文档

daprdocs 目录包含呈现到 Dapr Docs 网站的 markdown 文件。当构建文档网站时，会克隆此仓库并进行配置，使其内容与文档内容一起呈现。在编写文档时，请记住：

除了这些规则外，还应遵循 docs 指南中的所有规则。
所有文件和目录都应以 dotnet- 为前缀，以确保所有文件/目录名称在所有 Dapr 文档中全局唯一。

所有拉取请求都应努力在代码中包含 XML 文档，清楚地说明功能的作用以及存在的原因，以及对已发布文档的更改，以便为其他开发人员阐明您的更改如何改进 Dapr 框架。

GitHub Dapr Bot 命令

查看 daprbot 文档，了解您可以在该仓库中运行的常见任务的 GitHub 命令。例如，您可以在问题上评论 /assign 将其分配给自己。

提交签名

提交到 Dapr .NET SDK 的所有代码必须由编写它的开发者签名。这意味着每个提交都必须以以下内容结尾：

Signed-off-by: First Last flast@example.com

姓名和电子邮件地址必须与提交更改的用户的注册 GitHub 姓名和电子邮件地址匹配。我们使用机器人在拉取请求中检测这一点，如果此检查无法验证，我们将无法合并 PR。

如果您注意到 PR 由于早期 PR 历史中的 DCO 检查失败而未能验证，请考虑在本地压缩 PR 并重新提交，以确保签名声明包含在提交历史中。

语言、工具和流程

Dapr .NET SDK 中的所有源代码都是用 C# 编写的，并以最早支持的 .NET SDK 可用的最新语言版本为目标。截至 v1.16，这意味着同时支持 .NET 8 和 .NET 9。可用的最新语言版本是 C# version 12

贡献者欢迎使用他们最舒适开发的任何 IDE，但请不要随您的贡献提交 IDE 特定的偏好文件，因为这些文件将被拒绝。

2 - 为 Go SDK 做贡献

为 Dapr Go SDK 做贡献的指南

在为 Go SDK 做贡献时，应遵循以下规则和最佳实践。

示例

examples 目录包含代码示例，供用户运行以试用各种 Go SDK 包和扩展的特定功能。在编写新的和更新的示例时，请记住：

所有示例都应能在 Windows、Linux 和 MacOS 上运行。虽然 Go 代码在各个操作系统之间保持一致，但任何示例前/后命令都应通过 tabpane 提供选项
应包含下载/安装任何所需先决条件的步骤。对于全新操作系统安装的用户，应该能够从示例开始并无错误地完成。链接到外部下载页面也是可以的。

文档

daprdocs 目录包含 markdown 文件，这些文件被渲染到 Dapr 文档网站中。构建文档网站时，会克隆此仓库并对其进行配置，使其内容与文档内容一起渲染。在编写文档时，请记住：

除了这些规则外，还应遵循文档指南中的所有规则
所有文件和目录都应以 go- 为前缀，以确保所有文件/目录名称在所有 Dapr 文档中都是全局唯一的

3 - 为 Java SDK 贡献

为 Dapr Java SDK 贡献的指南

在为 Java SDK 贡献时，应遵循以下规则和最佳实践。

示例

examples 目录包含代码示例，供用户运行以试用各种 Java SDK 包和扩展的特定功能。在编写和更新示例时，请记住：

所有示例都应能在 Windows、Linux 和 MacOS 上运行。虽然 Java 代码在不同操作系统之间是一致的，但任何示例前后的命令都应通过 tabpane 提供选项
包含下载/安装任何所需先决条件的步骤。从全新操作系统安装开始的人应该能够开始并完成该示例而不会出错。指向外部下载页面的链接是可以的。

文档

daprdocs 目录包含 markdown 文件，这些文件被渲染到 Dapr Docs 网站上。构建文档网站时，此仓库被克隆并配置，使其内容与文档内容一起渲染。在编写文档时，请记住：

除了这些规则外，还应遵循文档指南中的所有规则
所有文件和目录应以 java- 为前缀，以确保所有文件/目录名称在所有 Dapr 文档中全局唯一

Github Dapr Bot 命令

查看 daprbot 文档，了解你可以在此仓库中运行的常见任务的 Github 命令。例如，你可以运行 /assign（作为问题评论）将问题分配给自己。

4 - 为 JavaScript SDK 做出贡献

为 Dapr JavaScript SDK 做出贡献的指南

在为 JavaScript SDK 做出贡献时，应遵循以下规则和最佳实践。

💡 您可以运行 npm pretty-fix 来对所有文件运行 prettier

提交指南

Dapr Javascript SDK 使用 Conventional Commits 规范。自动变更日志工具使用这些规范基于提交消息自动生成变更日志。以下是编写提交消息的指南，以支持此功能：

格式

type(scope)!: subject

type：提交类型是以下之一：
- feat：新功能。
- fix：bug 修复。
- docs：文档变更。
- refactor：特定代码部分的重构，不引入新功能或 bug 修复。
- style：代码风格改进。
- perf：性能改进。
- test：测试套件的变更。
- ci：CI 系统的变更。
- build：构建系统的变更（我们还没有构建系统，所以这不适用）。
- chore：其他不符合上述类型的变更。这不会出现在变更日志中。
scope：提交所更改的代码库部分。如果它更改了多个部分，或者没有修改特定部分，则留空不使用括号。示例：
- 添加 test 的提交：
```
test(actors): add an actor test
```
- 一次性更改多项的提交：
```
style: adopt eslint
```
对于示例的更改，scope 应该是示例名称加上 examples/ 前缀：
- ❌ fix(agnoster): commit subject
- ✅ fix(examples/http/actor): commit subject
!：放在 scope 之后（如果 scope 为空，则放在 type 之后），表示该提交引入了破坏性变更。
可选地，您可以指定一条消息，变更日志工具将向用户显示该消息，以指示更改内容以及他们可以如何处理。您可以使用多行来输入此消息；变更日志解析器将继续读取，直到提交消息结束或遇到空行。
示例（虚构）：
```
style(agnoster)!: change dirty git repo glyph

BREAKING CHANGE: the glyph to indicate when a git repository is dirty has
changed from a Powerline character to a standard UTF-8 emoji.

Fixes #420

Co-authored-by: Username <email>
```
subject：更改的简要描述。这将显示在变更日志中。如果您需要指定其他详细信息，可以使用提交正文，但这些内容不会可见。
格式技巧：提交主题可能包含：
- 通过编写 #issue 来链接相关问题或 PR。变更日志工具将突出显示这些内容：
```
feat(archlinux): add support for aura AUR helper (#9467)
```
- 通过使用反引号来格式化内联代码：反引号之间的文本也会被变更日志工具突出显示：
```
feat(shell-proxy): enable unexported `DEFAULT_PROXY` setting (#9774)
```

风格

尽量保持第一行提交内容简短。使用此提交风格很难做到这一点，但要尽量简洁，如果需要更多空间，可以使用提交正文。尽量确保提交主题清晰准确，使用户仅通过查看变更日志就能了解更改内容。

Github Dapr Bot 命令

查看 daprbot 文档，了解您可以在此仓库中运行的用于常见任务的 Github 命令。例如，您可以运行 /assign（作为问题的评论）来将问题分配给用户或用户组。

编码规则

为确保源代码的一致性，在工作时请记住这些规则：

所有功能或 bug 修复必须通过一个或多个规范（单元测试）进行测试。
所有公共 API 方法必须记录文档。
我们遵循 ESLint 推荐规则。

示例

examples 目录包含代码示例，供用户运行以试用各种 JavaScript SDK 包和扩展的特定功能。在编写新的和更新的示例时，请记住：

所有示例应该能够在 Windows、Linux 和 MacOS 上运行。虽然 JavaScript 代码在操作系统之间是一致的，但任何示例前/后命令应该通过 tabpane 提供选项。
包含下载/安装任何必要先决条件的步骤。从全新操作系统安装开始的人应该能够开始示例并完成它而不会出错。指向外部下载页面的链接是可以的。

文档

daprdocs 目录包含 markdown 文件，这些文件被渲染到 Dapr 文档网站。构建文档网站时，此仓库被克隆并配置，使其内容与文档内容一起渲染。在编写文档时，请记住：

除了这些规则外，还应遵循文档指南中的所有规则。
所有文件和目录应以 js- 为前缀，以确保所有文件/目录名称在所有 Dapr 文档中都是全局唯一的。

5 - 为 Python SDK 贡献

关于为 Dapr Python SDK 贡献的指南

当为 Python SDK 贡献时，应遵循以下规则和最佳实践。

示例

examples 目录包含代码示例，供用户运行以尝试各种 Python SDK 包和扩展的特定功能。在编写新的和更新的示例时，请注意：

所有示例都应能在 Windows、Linux 和 MacOS 上运行。虽然 Python 代码在操作系统之间保持一致，但任何示例前/后的命令应通过 tabpane 提供选项
包含下载/安装任何所需先决条件的步骤。对于一个全新操作系统安装的用户来说，应该能够开始示例并完成它而不会出现错误。指向外部下载页面的链接是可以的。

文档

daprdocs 目录包含渲染到 Dapr 文档网站的 markdown 文件。当构建文档网站时，该仓库会被克隆并配置，使其内容与文档内容一起渲染。在编写文档时，请注意：

除了这些规则外，还应遵循文档指南中的所有规则
所有文件和目录应以 python- 为前缀，以确保所有文件/目录名称在所有 Dapr 文档中全局唯一

Github Dapr Bot 命令

查看 daprbot 文档，了解您可以在此仓库中运行的常见任务的 GitHub 命令。例如，您可以运行 /assign（作为问题的评论）将问题分配给用户或用户组。

6 - 为 Rust SDK 做贡献

为 Dapr Rust SDK 做贡献的指南

在为 Rust SDK 做贡献时，应遵循以下规则和最佳实践。

示例

examples 目录包含代码示例，供用户运行以体验各种 Rust SDK 包和扩展的特定功能。它还托管用于验证的组件示例。在编写和更新示例时，请牢记：

所有示例应能在 Windows、Linux 和 MacOS 上运行。虽然 Rust 代码在操作系统之间是一致的，除了少数操作系统功能特性需要条件编译，但任何示例前/后命令都应通过 tabpane 提供选项
包含下载/安装任何必需先决条件的步骤。刚安装好操作系统的人应该能够开始示例并顺利完成，不会出现错误。链接到外部下载页面是可以的。
示例应通过验证，并包含机械化的 markdown 步骤，并添加到验证工作流中待定

文档

daprdocs 目录包含渲染到 Dapr 文档网站的 markdown 文件。当构建文档网站时，此仓库会被克隆并配置，使其内容与文档内容一起渲染。在编写文档时，请牢记：

除了这些规则外，还应遵循文档指南中的所有规则。
所有文件和目录应以 rust- 为前缀，以确保所有文件/目录名称在所有 Dapr 文档中全局唯一。

更新 Protobuf

要从 dapr/dapr 仓库拉取 protobuf，可以运行仓库根目录中的脚本，如下所示：

./update-protos.sh

默认情况下，脚本从 Dapr 仓库的 master 分支获取最新的 proto 更新。如果需要选择特定的发行版本，使用 -v 标志：

./update-protos.sh -v v1.13.0