SDK 贡献指引

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

1 - 为 .NET SDK 贡献

欢迎！

如果你正在阅读这篇文章，说明你可能对为 Dapr 和/或 Dapr .NET SDK 做出贡献感兴趣。欢迎加入这个项目，感谢你对贡献的兴趣！

请查看文档，了解 Dapr 的定义及其目标，并通过 Discord 联系我们。告诉我们你想如何贡献，我们很乐意提供想法和建议。

有很多方式可以为 Dapr 做出贡献：

• 为 Dapr 运行时 或 Dapr .NET SDK 提交错误报告
• 提出新的 运行时功能 或 SDK 功能
• 改进 Dapr 大项目 或 Dapr .NET SDK 专门 的文档
• 添加新的或改进现有的 组件，以实现各种构建块
• 增强 .NET 可插拔组件 SDK 功能
• 改进 Dapr .NET SDK 代码库和/或修复错误（详见下文）

如果你是代码库的新手，请在 Discord 的 #dotnet-sdk 频道中询问如何进行更改或提出一般性问题。你不需要获得许可即可进行任何工作，但请注意，如果某个问题已分配给某人，这表明可能已经有人开始处理它了。特别是如果自上次活动以来已经有一段时间，请随时联系他们，看看他们是否仍然有兴趣继续，或者你是否可以接手，并提交你的实现的 pull request。

如果你想将自己分配给一个问题，请在对话中回复 “/assign”，机器人会将你分配给它。

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

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

贡献规则和最佳实践

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

Pull Requests

仅包含格式更改的 pull request 通常不被鼓励。pull request 应该寻求修复错误、添加新功能或改进现有功能。

请尽量将你的 pull request 限制在单个问题上。涉及许多文件的广泛 PR 不太可能在短时间内被审查或接受。在单个 PR 中处理许多不同的问题使得很难确定你的代码是否完全解决了潜在问题，并使代码审查复杂化。

测试

所有 pull request 应包括单元和/或集成测试，以反映所添加或更改的内容，以便明确功能按预期工作。避免使用自动生成的测试，这些测试会多次重复测试相同的功能。相反，寻求通过验证更改的每个可能路径来提高代码覆盖率，以便未来的贡献者可以更轻松地导航你的逻辑轮廓，并更容易识别限制。

示例

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

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

文档

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

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

所有 pull request 应努力包括代码中的 XML 文档，清楚地指明功能的作用和原因，以及对已发布文档的更改，以便为其他开发人员澄清你的更改如何改进 Dapr 框架。

GitHub Dapr Bot 命令

查看 daprbot 文档 以获取你可以在此仓库中运行的常见任务的 Github 命令。例如，你可以在问题上评论 /assign 来将其分配给自己。

提交签署

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

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

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

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

语言、工具和流程

Dapr .NET SDK 中的所有源代码都是用 C# 编写的，并针对最新的语言版本可用于最早支持的 .NET SDK。截至 v1.15，这意味着因为 .NET 6 仍然受支持，最新的语言版本是 C# 版本 10。

截至 v1.15，支持以下 .NET 版本：

欢迎贡献者使用他们最熟悉的 IDE 进行开发，但请不要提交 IDE 特定的偏好文件，因为这些文件将被拒绝。

2 - 为 Go SDK 贡献

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

示例

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

• 所有示例应能在 Windows、Linux 和 MacOS 上运行。虽然 Go 代码在不同操作系统之间是一致的，但任何示例的前置/后置命令应通过 tabpane 提供不同的选项。
• 包含下载和安装任何必要前提条件的步骤。即使是刚安装操作系统的用户，也应该能够顺利开始并完成示例而不出现错误。可以链接到外部下载页面。

文档

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

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

3 - 为 Java SDK 贡献

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

示例

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

• 所有示例应能在 Windows、Linux 和 MacOS 上运行。虽然 Java 代码在不同操作系统上是一致的，但任何示例的前置或后续命令应通过 tabpane 提供不同的选项。
• 包含下载和安装所有必要前提条件的步骤。即使是全新安装操作系统的用户，也应该能够顺利开始并完成示例。可以链接到外部下载页面。

文档

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

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

4 - 贡献到 JavaScript SDK

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

💡 你可以运行 npm pretty-fix 来格式化所有文件

提交指南

Dapr JavaScript SDK 遵循 Conventional Commits 规范。自动生成的变更日志工具会根据提交信息自动生成变更日志。以下是编写提交信息的指南：

格式

type(scope)!: subject

• type: 提交的类型是以下之一：

  • feat: 新功能。
  • fix: 错误修复。
  • docs: 文档更改。
  • refactor: 重构特定代码部分，不引入新功能或错误修复。
  • style: 代码风格改进。
  • perf: 性能改进。
  • test: 测试套件的更改。
  • ci: CI 系统的更改。
  • build: 构建系统的更改（我们目前没有，所以不适用）。
  • chore: 其他不符合上述类型的更改。这不会出现在变更日志中。

• scope: 提交更改的代码库部分。如果更改了多个部分，或没有特定部分被修改，则留空，不加括号。 示例：

  • 添加 test 的提交：

  test(actors): add an actor test
  

  • 一次更改多项的提交：

  style: adopt eslint
  

  对于示例的更改，范围应为示例名称，前缀为 examples/：

  • ❌ fix(agnoster): commit subject
  • ✅ fix(examples/http/actor): commit subject

• !: 这个符号放在 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（作为问题的评论）来将问题分配给用户或用户组。

编码规则

为了确保源代码的一致性，请在工作时牢记以下规则：

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

示例

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

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

文档

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

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

5 - 为 Python SDK 贡献

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

示例

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

• 所有示例应在 Windows、Linux 和 MacOS 上均可运行。虽然 Python 代码在不同操作系统之间是一致的，但任何示例的前置或后续命令应通过 tabpane 提供不同操作系统的选项。
• 包含下载和安装所有必要前提条件的步骤。即使是刚安装操作系统的人也应该能够顺利开始并完成示例，而不会遇到错误。可以链接到外部下载页面。

文档

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

• 除了这些规则外，还应遵循 docs guide 中的所有规则。
• 所有文件和目录名称应以 python- 为前缀，以确保在所有 Dapr 文档中具有唯一性。

Github Dapr Bot 命令

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

6 - 贡献 Rust SDK

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

示例

examples 目录包含用户可以运行的代码示例，以尝试各种 Rust SDK 包和扩展的特定功能。它还包含用于验证的组件示例。在编写或更新示例时，请注意以下几点：

• 所有示例应能在 Windows、Linux 和 MacOS 上运行。虽然 Rust 代码在不同操作系统之间基本一致，但由于少量操作系统功能限制，任何示例的前置/后置命令都应通过 tabpane 提供不同选项。
• 包含下载和安装所有必要前提条件的步骤。刚安装操作系统的人应该能够顺利开始并完成示例而不出错。可以链接到外部下载页面。
• 示例应经过验证，并包含自动化的 markdown 步骤，并添加到验证工作流 TBA。

文档

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

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

更新 Protobufs

要从 dapr/dapr 仓库中提取 protobufs，您可以在仓库根目录运行以下脚本：

./update-protos.sh

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

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