为Dapr项目做贡献

• 1: 贡献概览
• 2: Dapr 演讲指南
• 3: Dapr 发展规划
• 4: 使用 GitHub Codespaces 进行贡献
• 5: Dapr 机器人参考
• 6: SDK 贡献指引
• 6.1: 为 .NET SDK 贡献
• 6.2: 为 Go SDK 贡献
• 6.3: 为 Java SDK 贡献
• 6.4: 贡献到 JavaScript SDK
• 6.5: 为 Python SDK 贡献
• 6.6: 贡献 Rust SDK
• 7: 文档贡献指南
• 7.1: 贡献者指南
• 7.2: 维护者指南
• 7.3: Dapr 文档模板建议
• 7.3.1: 概念文章模板
• 7.3.2: 快速入门指南模板
• 7.3.3: 操作指南模板

1 - 贡献概览

感谢您对Dapr项目的关注！ 本文档为您提供如何通过提交问题和拉取请求来为Dapr项目做出贡献的指南。您还可以通过其他方式参与，例如参加社区电话会议、对问题或拉取请求进行评论等。

有关社区参与和成员资格的更多信息，请参阅Dapr社区代码库。

Dapr代码库索引

以下是Dapr组织下的代码库列表，您可以在这些代码库中进行贡献：

1. 文档：此代码库包含Dapr的文档。您可以通过更新现有文档、修复错误或添加新内容来改善用户体验和清晰度。请参阅文档贡献指南。

2. 快速入门：快速入门代码库提供简单的分步指南，帮助用户快速上手Dapr。您可以通过创建新的快速入门、改进现有的快速入门或确保它们与最新功能保持同步来贡献。查看贡献指南。

3. 运行时：Dapr运行时代码库包含核心运行时组件。您可以通过修复错误、优化性能、实现新功能或增强现有功能来贡献。

4. 组件贡献：此代码库托管了Dapr的社区贡献组件集合。您可以通过添加新组件、改进现有组件或审查和测试社区的贡献来参与。

5. SDKs：Dapr SDKs为各种编程语言提供与Dapr交互的库。您可以通过改进SDK功能、修复错误或添加对新功能的支持来贡献。请参阅SDK贡献指南以获取特定SDK的详细信息。

6. CLI：Dapr CLI用于在本地开发机器或Kubernetes集群上设置Dapr以启动和管理Dapr实例。对CLI代码库的贡献包括添加新功能、修复错误、提高可用性，并确保与最新的Dapr版本兼容。请参阅开发指南以获取有关开发Dapr CLI的帮助。

问题

问题类型

在大多数Dapr代码库中，通常有4种类型的问题：

• 问题/错误：您发现了代码中的错误，并希望报告或创建一个问题来跟踪该错误。
• 问题/讨论：您有一些想法，需要在讨论中获得他人的意见，然后最终形成提案。
• 问题/提案：用于提出新想法或功能的项目。这允许在编写代码之前获得他人的反馈。
• 问题/问题：如果您需要帮助或有问题，请使用此问题类型。

提交之前

在提交问题之前，请确保您已检查以下内容：

1. 这是正确的代码库吗？
   • Dapr项目分布在多个代码库中。如果您不确定哪个代码库是正确的，请查看代码库列表。
2. 检查现有问题
   • 在创建新问题之前，请在开放问题中搜索，查看该问题或功能请求是否已被提交。
   • 如果您发现您的问题已经存在，请进行相关评论并添加您的反应。使用反应：
     • 👍 赞成
     • 👎 反对
3. 对于错误
   • 检查这不是环境问题。例如，如果在Kubernetes上运行，请确保先决条件已到位。（state存储、bindings等）
   • 您拥有尽可能多的数据。这通常以日志和/或堆栈跟踪的形式出现。如果在Kubernetes或其他环境中运行，请查看Dapr服务（运行时、operator、placement服务）的日志。有关如何获取日志的更多详细信息，请参阅此处。
4. 对于提案
   • 许多对Dapr运行时的更改可能需要对API进行更改。在这种情况下，讨论潜在功能的最佳地点是主要的Dapr代码库。
   • 其他示例可能包括bindings、state存储或全新的组件。

拉取请求

所有贡献都通过拉取请求提交。要提交建议的更改，请遵循以下工作流程：

1. 确保已提出问题（错误或提案），以设定您即将进行的贡献的期望。
2. 分叉相关代码库并创建新分支
   • 一些Dapr代码库支持Codespaces，为您提供即时环境以构建和测试您的更改。
   • 有关设置Dapr开发环境的更多信息，请参阅开发Dapr文档。
3. 创建您的更改
   • 代码更改需要测试
4. 更新相关文档以反映更改
5. 使用DCO签署提交并打开PR
6. 等待CI过程完成并确保所有检查通过
7. 项目的维护者将被分配，您可以在几天内期待审查

使用草稿PR以获得早期反馈

在投入过多时间之前进行沟通的好方法是创建一个“草稿”PR并与您的审阅者分享。标准做法是在PR的标题中添加“[WIP]”前缀，并分配do-not-merge标签。这将让查看您PR的人知道它尚未成熟。

使用第三方代码

• 第三方代码必须包含许可证。

开发者来源证书：签署您的工作

每次提交都需要签署

开发者来源证书（DCO）是一种轻量级方式，供贡献者证明他们编写或以其他方式有权提交他们贡献给项目的代码。以下是DCO的完整文本，经过重新格式化以提高可读性：

通过对该项目进行贡献，我证明：
    (a) 该贡献完全或部分由我创建，并且我有权根据文件中指明的开源许可证提交它；或者
    (b) 该贡献基于我所知的适当开源许可证覆盖的先前工作，并且我有权根据该许可证提交该工作及其修改，无论是由我完全或部分创建的，均根据相同的开源许可证（除非我被允许根据不同的许可证提交），如文件中所示；或者
    (c) 该贡献是由其他人直接提供给我的，他们证明了(a)、(b)或(c)，而我没有修改它。
    (d) 我理解并同意该项目和贡献是公开的，并且贡献的记录（包括我提交的所有个人信息，包括我的签署）将被无限期地维护，并可能根据该项目或涉及的开源许可证进行再分发。

贡献者通过在提交消息中添加Signed-off-by行来签署他们遵守这些要求。

这是我的提交消息
Signed-off-by: Random J Developer <random@developer.example.org>

Git甚至有一个-s命令行选项，可以自动将其附加到您的提交消息中：

$ git commit -s -m '这是我的提交消息'

每个拉取请求都会检查拉取请求中的提交是否包含有效的Signed-off-by行。

我没有签署我的提交，现在怎么办？！

别担心 - 您可以轻松地重放您的更改，签署它们并强制推送它们！

git checkout <branch-name>
git commit --amend --no-edit --signoff
git push --force-with-lease <remote-name> <branch-name>

行为准则

请参阅Dapr社区行为准则。

2 - Dapr 演讲指南

我们欢迎社区成员分享关于 Dapr 的演讲，并推广 Dapr 的各种强大功能！我们提供了一个 PowerPoint 模板文件，帮助您快速开始。

brew install --cask font-space-grotesk

如何进行 Dapr 演讲

• 首先下载 Dapr 演示文稿，其中包含您进行 Dapr 演讲所需的幻灯片和图表。
• 接下来，查看文档以确保您理解 概念。
• 使用 Dapr 快速入门 和 示例 仓库，展示如何使用 Dapr。

过往的 Dapr 演讲

其他资源

在 社区 仓库中可以找到更多 Dapr 资源。

3 - Dapr 发展规划

请访问此文档以了解 Dapr 项目的发展规划。

4 - 使用 GitHub Codespaces 进行贡献

GitHub Codespaces 是为 Dapr 仓库做出贡献的最简单方式。只需点击一下，您就可以在浏览器中获得一个已准备好的环境，包含所有必要的前置条件。

功能

• 一键运行：获取一个专用且沙盒化的环境，所有必需的框架和包都已准备就绪。
• 按使用计费：只需为您在 Codespaces 中开发的时间付费。当不使用时，环境会自动关闭。
• 便携性：可以在浏览器中运行，也可以在 Visual Studio Code 中运行，或使用 SSH 连接。

在 Codespace 中打开 Dapr 仓库

要在 Codespace 中打开 Dapr 仓库，请从仓库主页选择“Code”并选择“Open with Codespaces”：

如果您还没有 fork 该仓库，创建 Codespace 时会自动为您创建一个 fork，并在 Codespace 中使用它。

支持的仓库

• dapr/dapr
• dapr/components-contrib
• dapr/cli
• dapr/docs
• dapr/python-sdk

在 Codespace 中开发 Dapr 组件

开发新的 Dapr 组件需要同时处理 dapr/components-contrib 和 dapr/dapr 仓库。建议将这两个文件夹并排放置在 /workspaces 目录中。

如果您从 dapr/dapr 创建了 Codespace

如果您的 Codespaces 是从 dapr/dapr 仓库或其 fork 启动的，您需要在 /workspaces/components-contrib 中克隆 dapr/components-contrib 仓库（或其 fork）。

首先，确保您已通过 GitHub CLI 进行身份验证：

# 运行此命令并按照提示进行操作
# 大多数用户应接受默认选择
gh auth login

克隆仓库：

# 如果您想使用您 fork 的 dapr/components-contrib，请将其替换为您的 fork（例如 "yourusername/components-contrib"）
# 确保在执行此操作之前已 fork 该仓库
REPO=dapr/components-contrib
cd /workspaces
gh repo clone "$REPO" /workspaces/components-contrib

然后，将文件夹添加到当前工作区：

code -a /workspaces/components-contrib

如果您从 dapr/components-contrib 创建了 Codespace

如果您的 Codespaces 是从 dapr/components-contrib 仓库或其 fork 启动的，您需要在 /workspaces/dapr 中克隆 dapr/dapr 仓库（或其 fork）。

首先，确保您已通过 GitHub CLI 进行身份验证：

# 运行此命令并按照提示进行操作
# 大多数用户应接受默认选择
gh auth login

克隆仓库：

# 如果您想使用您 fork 的 dapr/dapr，请将其替换为您的 fork（例如 "yourusername/dapr"）
# 确保在执行此操作之前已 fork 该仓库
REPO=dapr/dapr
cd /workspaces
gh repo clone "$REPO" /workspaces/dapr

然后，将文件夹添加到当前工作区：

code -a /workspaces/dapr

相关链接

• GitHub 文档

5 - Dapr 机器人参考

Dapr 机器人通过一系列命令来帮助处理 Dapr 组织中的常见任务。它可以为每个代码库单独配置（示例），并能够在特定事件发生时运行。以下是命令列表及其在各个代码库中的实现。

命令参考

标签参考

您可以通过使用 created-by/dapr-bot 标签查询由 Dapr 机器人创建的 issue（查询）。

6 - SDK 贡献指引

6.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 特定的偏好文件，因为这些文件将被拒绝。

6.2 - 为 Go SDK 贡献

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

示例

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

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

文档

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

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

6.3 - 为 Java SDK 贡献

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

示例

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

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

文档

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

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

6.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 文档中都是全局唯一的。

6.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.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

7 - 文档贡献指南

7.1 - 贡献者指南

在本指南中，您将学习如何为 Dapr 文档库 做出贡献。由于 Dapr 文档发布在 docs.dapr.io，您需要确保您的贡献能够正确编译和发布。

先决条件

在为 Dapr 文档做贡献之前：

• 查看 关于 Dapr 项目贡献的一般指导。
• 使用 Hugo 和 Docsy 主题安装并设置您的本地环境。请按照库中的 README.md 中的说明进行操作。
• 分叉并克隆 文档库。

分支指导

Dapr 文档的分支管理与大多数代码库不同。没有主分支，每个分支都与运行时发布的主要和次要版本相匹配。完整列表请访问 Docs repo。

通常，您所有的文档更新都应提交到 Dapr 最新版本的文档分支。最新版本是默认分支 [https://github.com/dapr/docs]。例如，如果您正在修复拼写错误、添加注释或澄清某个点，请将您的更改提交到默认的 Dapr 分支。

对于适用于候选发布或预发布版本的文档更改，请将您的更改指向该特定分支。例如，如果您正在记录即将对组件或运行时的更改，请将您的更改提交到预发布分支。

风格和语气

在所有 Dapr 文档中应遵循风格和语气惯例，以确保所有文档的一致性：

图表和图像

图表和图像是文档页面中无价的视觉辅助工具。使用 Dapr 图表模板套件 中的图表样式和图标。

为您的文档创建图表的过程：

1. 下载 Dapr 图表模板套件 以使用图标和颜色。
2. 添加新幻灯片并创建您的图表。
3. 将图表截屏为高分辨率 PNG 文件并保存在 images 文件夹中。
4. 使用概念或构建块的命名约定命名您的 PNG 文件，以便它们被分组。

• 例如：service-invocation-overview.png。
• 有关使用短代码调用图像的更多信息，请参见下面的 图像指导 部分。

1. 使用 HTML <image> 标签将图表添加到文档中的适当部分。
2. 在您的 PR 中，评论图表幻灯片（而不是截屏），以便维护者可以审查并将其添加到图表套件中。

贡献新文档页面

如果您正在创建新文章，请确保您：

• 将新文档放置在层次结构中的正确位置。
• 避免创建新部分。大多数情况下，正确的位置已经在文档层次结构中。
• 包含完整的 Hugo front-matter。

选择下面的主题类型以查看建议的模板，帮助您入门。

docs.dapr.io 的要求

确保您的贡献不会破坏网站构建。Hugo 构建网站的方式需要遵循以下指导：

文件和文件夹名称

文件和文件夹名称应在全局范围内唯一。 - \service-invocation - service-invocation-overview.md

Front-matter

Front-matter 是将常规 markdown 文件升级为 Hugo 兼容文档以呈现到导航栏和目录中的内容。

每个页面都需要在文档顶部有一个这样的部分：

---
type: docs
title: "页面标题"
linkTitle: "导航栏短标题"
weight: (数字)
description: "1+ 句描述文章"
---

示例

---
type: docs
title: "服务调用概述"
linkTitle: "概述"
weight: 10
description: "Dapr 服务调用的快速概述以及如何在应用程序中使用它来调用服务"
---

权重决定了左侧边栏中页面的顺序，0 为最顶部。

Front-matter 应包括所有字段，包括 type、title、linkTitle、weight 和 description。

• title 应为 1 句，末尾无句号
• linkTitle 应为 1-3 个词，除了 How-to 前缀。
• description 应为 1-2 句，说明读者将在本文档中学习、完成或执行的内容。

根据 样式惯例，标题应仅大写第一个词和专有名词，除了 “How-To:”

• “开始使用 Dapr 服务调用”
• “How-To: 设置本地 Redis 实例”

引用其他页面

Hugo ref 和 relref 短代码 用于引用其他页面和部分。这些短代码还允许在页面被错误重命名或删除时中断构建。

例如，这个短代码，与其余的 markdown 页面内联书写，将链接到该部分/文件夹名称的 _index.md：

{{< ref "folder" >}}

而这个短代码将链接到特定页面：

{{< ref "page.md" >}}

所有页面和文件夹需要有 全局唯一名称 以便 ref 短代码正常工作。如果有重复名称，构建将中断并抛出错误。

引用其他页面中的部分

要引用其他页面中的特定部分，请在引用的末尾添加 #section-short-name。

一般规则是，部分短名称是部分标题的文本，全部小写，空格改为 “-”. 您可以通过以下方式检查部分短名称：

1. 访问网站页面。
2. 点击部分旁边的链接图标 (🔗)。
3. 查看 URL 在导航栏中的呈现方式。
4. 复制 “#” 后的内容作为您的部分短名称。

例如，对于此特定部分，完整的页面和部分引用将是：

{{< ref "contributing-docs.md#referencing-sections-in-other-pages" >}}

短代码

以下是撰写 Dapr 文档的有用短代码

图像

Docsy 和 Hugo 使用的 markdown 规范没有提供使用 markdown 符号调整图像大小的选项。相反，使用原始 HTML。

首先将图像放在 /daprdocs/static/images 下，命名约定为 [page-name]-[image-name].[png|jpg|svg]。

然后链接到图像：

<img src="/images/[image-filename]" width=1000 alt="图像描述">

不要忘记设置 alt 属性以保持文档的可读性和可访问性。

示例

此 HTML 将在 overview.md 页面上显示 dapr-overview.png 图像：

<img src="/images/overview-dapr-overview.png" width=1000 alt="Dapr 及其构建块的概述图">

选项卡内容

选项卡通过 Hugo 短代码 实现。

整体格式是：

{{< tabpane text=true>}}

{{% tab header="[Tab1]" %}}
[Tab1 的内容]
{{% /tab %}}

{{% tab header="[Tab2]" %}}
[Tab2 的内容]
{{% /tab %}}

{{< /tabpane >}}

您撰写的所有内容都将被渲染为 markdown，因此您可以包含图像、代码块、YouTube 视频等。

示例

{{< tabpane text=true >}}

{{% tab header="Windows" %}}
```powershell
powershell -Command "iwr -useb https://raw.githubusercontent.com/dapr/cli/master/install/install.ps1 | iex"
```
{{% /tab %}}

{{% tab header="Linux" %}}
```bash
wget -q https://raw.githubusercontent.com/dapr/cli/master/install/install.sh -O - | /bin/bash
```
{{% /tab %}}

{{% tab header="MacOS" %}}
```bash
brew install dapr/tap/dapr-cli
```
{{% /tab %}}

{{< /tabpane >}}

此示例将呈现为：

• Windows
• Linux
• MacOS

powershell -Command "iwr -useb https://raw.githubusercontent.com/dapr/cli/master/install/install.ps1 | iex"

wget -q https://raw.githubusercontent.com/dapr/cli/master/install/install.sh -O - | /bin/bash

brew install dapr/tap/dapr-cli

YouTube 视频

Hugo 可以使用短代码自动嵌入 YouTube 视频：

{{< youtube [VIDEO ID] >}}

示例

给定视频 https://youtu.be/dQw4w9WgXcQ

短代码将是：

{{< youtube dQw4w9WgXcQ >}}

按钮

要在网页中创建按钮，请使用 button 短代码。

可选的 “newtab” 参数将指示页面是否应在新选项卡中打开。选项为 “true” 或 “false”。默认值为 “false”，页面将在同一选项卡中打开。

链接到外部页面

{{< button text="我的按钮" link="https://example.com" >}}

链接到其他文档页面

您也可以在按钮中引用页面：

{{< button text="我的按钮" page="contributing" newtab="true" >}}

按钮颜色

您可以使用 Bootstrap 颜色自定义颜色：

{{< button text="我的按钮" link="https://example.com" color="primary" >}}
{{< button text="我的按钮" link="https://example.com" color="secondary" >}}
{{< button text="我的按钮" link="https://example.com" color="success" >}}
{{< button text="我的按钮" link="https://example.com" color="danger" >}}
{{< button text="我的按钮" link="https://example.com" color="warning" >}}
{{< button text="我的按钮" link="https://example.com" color="info" >}}

我的按钮 我的按钮 我的按钮 我的按钮 我的按钮 我的按钮

参考

Docsy 撰写指南

翻译

Dapr 文档支持使用 git 子模块和 Hugo 内置语言支持将语言翻译添加到文档中。

您可以在 PR 1286 中找到添加中文语言支持的示例 PR。

添加语言的步骤：

• 在文档库中打开一个问题，请求创建一个新的语言特定文档库

• 创建后，在文档库中创建一个 git 子模块：

  git submodule add <remote_url> translations/<language_code>
  

• 在 daprdocs/config.toml 中添加一个语言条目：

   [languages.<language_code>]
     title = "Dapr 文档"
     weight = 3
     contentDir = "content/<language_code>"
     languageName = "<language_name>"
  

• 在 daprdocs/config.toml 中创建一个挂载：

  [[module.mounts]]
    source = "../translations/docs-<language_code>/content/<language_code>"
    target = "content"
    lang = "<language_code>"
  

• 根据需要为所有其他翻译目录重复上述步骤。

下一步

通过复制并从 Dapr 文档模板 开始。

7.2 - 维护者指南

在本指南中，您将学习如何履行 Dapr 文档维护者和审批者的日常职责。要成功完成这些任务，您需要在 dapr/docs 仓库中拥有审批者或维护者的权限。

如果您想了解如何为 Dapr 文档做出贡献，请查看 贡献者指南。

分支管理指南

Dapr 文档的分支管理与大多数代码仓库不同。没有 main 分支，每个分支都与运行时发布的主要和次要版本相对应。

完整的分支列表请访问 文档仓库。

阅读 贡献者指南 以获取有关发布分支的更多信息。

从当前发布分支合并到预发布分支

作为文档审批者或维护者，您需要定期进行合并操作，以确保预发布分支与当前发布分支保持同步。建议每周将当前分支的更新合并到预发布分支。

以下步骤中，将 v1.0 视为当前发布版本，将 v1.1 视为即将发布版本。

1. 在 Visual Studio Code 中打开 Dapr 文档仓库。

2. 在本地仓库中，切换到最新分支 (v1.0) 并同步更改：

   git pull upstream v1.0
   git push origin v1.0
   

3. 切换到即将发布的分支 (v1.1) 并同步更改：

   git pull upstream v1.1
   git push origin v1.1
   

4. 基于即将发布的版本创建一个新分支：

   git checkout -b upmerge_MM-DD
   

5. 在终端中，从最新发布分支合并到新建的合并分支：

   git merge --no-ff --no-commit v1.0
   

6. 在终端中，确保合并的文件准确无误。在 VS Code 中检查是否有合并冲突。删除不需要合并的配置更改或版本信息。

7. 提交暂存的更改并推送到合并分支 (upmerge_MM-DD)。

8. 从合并分支创建一个 PR 到即将发布的分支 (v1.1)。

9. 审查 PR，确保没有意外更改被推送到合并分支。

发布流程

Dapr 文档必须与 Dapr 项目发布中包含的功能和更新保持一致。在 Dapr 发布日期之前，请确保：

• 所有新功能或更新都已充分记录和审查。
• 即将发布的文档 PR 指向发布分支。

以下步骤中，将 v1.0 视为最新发布版本，将 v1.1 视为即将发布版本。

文档的发布流程包括以下内容：

• 将最新发布版本合并到即将发布的分支
• 更新最新和即将发布的 Hugo 配置文件
• 为下一个版本创建新的 Azure 静态 Web 应用
• 为下一个版本的网站创建新的 DNS 条目
• 为下一个版本创建新的 git 分支

合并操作

首先，从最新发布版本合并到即将发布的分支，执行 文档合并操作。

更新 Hugo 配置

合并后，准备文档分支以进行发布。在两个单独的 PR 中，您需要：

• 存档最新发布版本。
• 将预览/发布分支作为文档的当前在线版本。
• 创建一个新的预览分支。

最新发布版本

这些步骤将准备最新发布分支以进行存档。

1. 在 VS Code 中打开 Dapr 文档仓库。

2. 切换到最新分支 (v1.0) 并同步更改：

   git pull upstream v1.0
   git push origin v1.0
   

3. 基于最新发布创建一个新分支：

   git checkout -b release_v1.0
   

4. 在 VS Code 中，导航到 /daprdocs/config.toml。

5. 在 # Versioning 部分（大约第 154 行）添加以下 TOML：

   version_menu = "v1.0"
   version = "v1.0"
   archived_version = true
   url_latest_version = "https://docs.dapr.io"
   
   [[params.versions]]
     version = "v1.2 (preview)"
     url = "v1-2.docs.dapr.io"
   [[params.versions]]
     version = "v1.1 (latest)"
     url = "#"
   [[params.versions]]
     version = "v1.0"
     url = "https://v1-0.docs.dapr.io"
   

6. 删除 .github/workflows/website-root.yml。

7. 提交暂存的更改并推送到您的分支 (release_v1.0)。

8. 从 release_v1.0 打开一个 PR 到 v1.0。

9. 让文档维护者或审批者进行审查。等待合并 PR 直到发布。

即将发布版本

这些步骤将准备即将发布的分支以提升为最新发布。

1. 在 VS Code 中打开 Dapr 文档仓库。

2. 切换到即将发布的分支 (v1.1) 并同步更改：

   git pull upstream v1.1
   git push origin v1.1
   

3. 基于即将发布的版本创建一个新分支：

   git checkout -b release_v1.1
   

4. 在 VS Code 中，导航到 /daprdocs/config.toml。

5. 更新第 1 行为 baseURL - https://docs.dapr.io/。

6. 更新 # Versioning 部分（大约第 154 行）以显示正确的版本和标签：

   # Versioning
   version_menu = "v1.1 (latest)"
   version = "v1.1"
   archived_version = false
   url_latest_version = "https://docs.dapr.io"
   
   [[params.versions]]
     version = "v1.2 (preview)"
     url = "v1-2.docs.dapr.io"
   [[params.versions]]
     version = "v1.1 (latest)"
     url = "#"
   [[params.versions]]
     version = "v1.0"
     url = "https://v1-0.docs.dapr.io"
   

7. 导航到 .github/workflows/website-root.yml。

8. 更新触发工作流的分支：

   name: Azure Static Web App Root
   
   on:
     push:
       branches:
         - v1.1
     pull_request:
       types: [opened, synchronize, reopened, closed]
       branches:
         - v1.1
   

9. 导航到 /README.md。

10. 更新版本表：

| Branch                                                       | Website                    | Description                                                                                      |
| ------------------------------------------------------------ | -------------------------- | ------------------------------------------------------------------------------------------------ |
| [v1.1](https://github.com/dapr/docs) (primary)               | https://docs.dapr.io       | 最新 Dapr 发布文档。拼写错误修正、澄清和大多数文档都在这里。 |
| [v1.2](https://github.com/dapr/docs/tree/v1.2) (pre-release) | https://v1-2.docs.dapr.io/ | 预发布文档。仅适用于 v1.2+ 的文档更新在这里。                |

1. 更新 dapr-latest-version.html 短代码部分为新的次要/补丁版本（在此示例中为 1.1.0 和 1.1）。
2. 提交暂存的更改并推送到您的分支 (release_v1.1)。
3. 从 release/v1.1 打开一个 PR 到 v1.1。
4. 让文档维护者或审批者进行审查。等待合并 PR 直到发布。

未来预览分支

创建预览分支

1. 在 GitHub UI 中，选择分支下拉菜单并选择 查看所有分支。
2. 点击 新建分支。
3. 在 新分支名称 中，输入预览分支版本号。在此示例中，它将是 v1.2。
4. 选择 v1.1 作为来源。
5. 点击 创建新分支。

配置预览分支

1. 在终端窗口中，导航到 docs 仓库。

2. 切换到即将发布的分支 (v1.1) 并同步更改：

   git pull upstream v1.1
   git push origin v1.1
   

3. 基于 v1.1 创建一个新分支并命名为 v1.2：

git checkout -b release_v1.1

1. 重命名 .github/workflows/website-v1-1.yml 为 .github/workflows/website-v1-2.yml。

2. 在 VS Code 中打开 .github/workflows/website-v1-2.yml 并更新名称、触发器和部署目标为 1.2：

   name: Azure Static Web App v1.2
   
   on:
     push:
       branches:
         - v1.2
     pull_request:
       types: [opened, synchronize, reopened, closed]
       branches:
         - v1.2
   
    ...
   
        with:
          azure_static_web_apps_api_token: ${{ secrets.AZURE_STATIC_WEB_APPS_V1_2 }}
          repo_token: ${{ secrets.GITHUB_TOKEN }}
   
    ...
   
        with:
          azure_static_web_apps_api_token: ${{ secrets.AZURE_STATIC_WEB_APPS_V1_2 }}
          skip_deploy_on_missing_secrets: true
   

3. 导航到 daprdocs/config.toml 并更新 baseURL 以指向新的预览网站：

   baseURL = "https://v1-2.docs.dapr.io"
   

4. 更新 # GitHub Information 和 # Versioning 部分（大约第 148 行）以显示正确的版本和标签：

   # GitHub Information
   github_repo = "https://github.com/dapr/docs"
   github_project_repo = "https://github.com/dapr/dapr"
   github_subdir = "daprdocs"
   github_branch = "v1.2"
   
   # Versioning
   version_menu = "v1.2 (preview)"
   version = "v1.2"
   archived_version = false
   url_latest_version = "https://docs.dapr.io"
   
   [[params.versions]]
     version = "v1.2 (preview)"
     url = "#"
   [[params.versions]]
     version = "v1.1 (latest)"
     url = "https://docs.dapr.io"
   [[params.versions]]
     version = "v1.0"
     url = "https://v1-0.docs.dapr.io"
   

5. 提交暂存的更改并推送到针对 v1.2 分支的新 PR。

6. 在发布后以及其他 v1.0 和 v1.1 PR 合并后再合并 PR。

为未来发布创建新网站

接下来，为未来的 Dapr 发布创建一个新网站。为此，您需要：

• 部署一个 Azure 静态 Web 应用。
• 通过 CNCF 请求配置 DNS。

先决条件

• 在 dapr/docs 仓库中拥有文档维护者身份。
• 访问活动的 Dapr Azure 订阅，并具有创建资源的贡献者或所有者访问权限。
• 在您的机器上安装 Azure Developer CLI。
• 您自己的 dapr/docs 仓库 的分叉已克隆到您的机器。

部署 Azure 静态 Web 应用

为未来的 Dapr 发布部署一个新的 Azure 静态 Web 应用。在此示例中，我们使用 v1.1 作为未来发布。

1. 在终端窗口中，导航到 dapr/docs 目录中的 iac/swa 文件夹。

   cd .github/iac/swa
   

2. 使用 Dapr Azure 订阅登录 Azure Developer CLI (azd)。

   azd login
   

3. 在浏览器提示中，验证您正在以 Dapr 身份登录并完成登录。

4. 在新终端中，替换以下值为您偏好的网站值。

   export AZURE_RESOURCE_GROUP=rg-dapr-docs-test
   export IDENTITY_RESOURCE_GROUP=rg-my-identities
   export AZURE_STATICWEBSITE_NAME=daprdocs-latest
   

5. 创建一个新的 azd 环境。

   azd env new
   

6. 当提示时，输入一个新的环境名称。在此示例中，您可以将环境命名为：dapr-docs-v1-1。

7. 环境创建完成后，使用以下命令将 Dapr 文档 SWA 部署到新环境中：

   azd up
   

8. 当提示时，选择一个 Azure 订阅和位置。将这些与 Dapr Azure 订阅匹配。

在 Azure 门户中配置 SWA

前往 Azure 门户 中的 Dapr 订阅，并验证您的新 Dapr 文档站点是否已部署。

可选地，使用门户中的 静态 Web 应用 > 访问控制 (IAM) 刀片授予正确的最小权限以进行入站发布和对依赖项的出站访问。

配置 DNS

1. 在 Azure 门户中，从您刚刚创建的新 SWA 中，导航到左侧菜单中的 自定义域。

2. 复制 Web 应用的 “CNAME” 值。

3. 使用您自己的帐户，提交 CNCF 工单 以创建一个新的域名映射到您复制的 CNAME 值。对于此示例，要为 Dapr v1.1 创建一个新域，您将请求映射到 v1-1.docs.dapr.io。

   请求解决可能需要一些时间。

4. 确认新域后，返回到门户中的静态 Web 应用。

5. 导航到 自定义域 刀片并选择 + 添加。

6. 选择 其他 DNS 上的自定义域。

7. 在 域名 下输入 v1-1.docs.dapr.io。点击 下一步。

8. 将 主机名记录类型 保持为 CNAME，并复制 值 的值。

9. 点击 添加。

10. 导航到 https://v1-1.docs.dapr.io 并验证空白网站是否正确加载。

您可以为任何预览版本重复这些步骤。

在新的 Dapr 发布日期

1. 等待所有代码/容器/Helm 图表发布。
2. 合并从 release_v1.0 到 v1.0 的 PR。删除 release/v1.0 分支。
3. 合并从 release_v1.1 到 v1.1 的 PR。删除 release/v1.1 分支。
4. 合并从 release_v1.2 到 v1.2 的 PR。删除 release/v1.2 分支。

恭喜发布新文档！🚀 🎉 🎈

拉取 SDK 文档更新

SDK 文档位于每个 SDK 仓库中。对 SDK 文档所做的更改会推送到相关的 SDK 仓库。例如，要更新 Go SDK 文档，您需要将更改推送到 dapr/go-sdk 仓库。在您将最新的 dapr/go-sdk 提交拉入 dapr/docs 当前版本分支之前，您的 Go SDK 文档更新不会反映在 Dapr 文档站点上。

要将 SDK 文档更新带到 Dapr 文档站点，您需要执行一个简单的 git pull。此示例涉及 Go SDK，但适用于所有 SDK。

1. 将最新的上游拉入您的本地 dapr/docs 版本分支。

2. 切换到 dapr/docs 目录的根目录。

3. 切换到 Go SDK 仓库。此命令将您从 dapr/docs 上下文切换到 dapr/go-sdk 上下文。

   cd sdkdocs/go
   

4. 切换到 dapr/go-sdk 中的 main 分支。

   git checkout main
   

5. 拉取最新的 Go SDK 提交。

   git pull upstream main
   

6. 切换到 dapr/docs 上下文以提交、推送并创建 PR。

下一步

有关为 Dapr 文档做出贡献的指导，请阅读 贡献者指南。

7.3 - Dapr 文档模板建议

7.3.1 - 概念文章模板

贡献新的概念或概述文章

概念（或概述）文章旨在回答以下问题：

• 为什么这个功能对你很重要？
• 它能帮助你解决哪些问题？

尽管组件、API 或 SDK 规范可以帮助读者理解如何使用这些功能，概念文章则提供了更深入的背景和上下文。请链接到规范文章，但尽量避免简单重复规范内容。

在为你的概念文章命名时，确保其名称、参数和术语与规范保持一致。如有必要，请同时更新两者。

了解更多关于为 Dapr 文档做贡献的信息，例如前置内容和短代码。

模板

---
type: #必填; docs
title: #必填; 简洁明了的标题
linkTitle: #必填; 简短标题
weight: #必填; 根据层级使用正确的权重
description: #必填; 对文章内容的简短描述
---

<!--
在打开 PR 之前，删除此模板中的所有注释。
-->

<!-- 
H1: Hugo 前置内容中的标题作为文章的 markdown H1。
-->

<!-- 简介段落  
必填。简要介绍文章将涵盖的概念。链接到适当的参考、规范或操作指南以提供上下文。 -->

<!-- 
如果可能，包含图表或图片。
-->

## <章节 1 H2>

<!-- 
在此添加你的内容。
-->

## <章节 2 H2>

<!-- 
每个 H2 步骤应以名词/描述性词语开头。
-->

## <章节 3 H2>

<!--
在此添加你的内容。
-->

<!--
在适用的地方，包含图表或图片。
-->

## 体验 <概念>

<!-- 
如果适用，包含一个部分，链接到相关的快速开始、操作指南或教程。
--> 

### 快速开始和教程

想要体验 Dapr <主题> API？通过以下快速开始和教程来了解 <主题> 的实际应用：

| 快速开始/教程 | 描述 |
| ------------------- | ----------- |
| [<主题> 快速开始](link) | 快速开始的描述。 |
| [<主题> 教程](link) | 教程的描述。 |

### 在你的应用中直接使用 <主题>

想跳过快速开始？没问题。你可以在你的应用中直接使用 <主题> 构建块。在[Dapr 安装完成](link)后，你可以开始使用 <主题> API，从[<主题> 操作指南](link)开始。

-->

## 下一步

<!--
链接到相关页面和示例。例如，相关的 API 规范，相关的构建块等。
-->

7.3.2 - 快速入门指南模板

贡献新的快速入门指南

Dapr 快速入门指南包含一些简明的指令，帮助读者完成一个预先准备好的快速入门项目，这些项目保存在 dapr/quickstarts 仓库中。这些快速入门将整个功能或构建块集中在一起，使读者能够轻松体验其工作原理，而不影响他们自己的项目。

快速入门指令应当简洁明了。快速入门指南的唯一目的是简单地指导读者完成准备好的快速入门。如果您想解释快速入门背后的概念，请将读者引导到相关的概念文章以获取更多背景信息。

了解更多关于如何贡献 Dapr 文档的信息，例如前置内容和短代码。

模板

---
type: #必填; docs
title: #必填; "快速入门：简洁明了的标题"
linkTitle: #必填; 这将在文档目录中显示
weight: #必填; 根据层级使用正确的权重
description: #必填; 一句话描述文章的预期内容
---

<!--
在提交 PR 之前，删除此模板中的所有注释。
-->

<!-- 
H1：Hugo 前置内容中的标题作为文章的 markdown H1。
-->

<!-- 引言段落  
必填。简要介绍快速入门将涵盖的内容。链接到适当的概念或概述文档以提供背景。 -->

<!-- 
如果可能，包含一个图表或图像。
-->

<!-- 
确保快速入门包含多个编程语言的示例。
-->

## 前置条件

<!--
列出读者在开始快速入门之前可能需要准备的内容，以确保顺利完成。
-->

## 步骤 1：设置环境

<!-- 
提供快速入门示例的链接，供读者克隆。
-->

## 步骤 2：<操作或任务>

<!-- 
每个 H2 步骤应以动词/动作词开头。
-->

<!--
尽可能包含代码片段。
-->

## 告诉我们您的想法！

我们正在不断努力改进我们的快速入门示例，并重视您的反馈。您觉得这个快速入门有帮助吗？您有改进建议吗？

欢迎加入我们的 [discord 频道](https://discord.gg/22ZtJrNe)进行讨论。

<!-- 由于 Dapr 是一个开放的贡献者社区，请确保提供 discord 讨论的链接以欢迎反馈。
-->

## 下一步

<!--
链接到相关页面和示例。例如，构建块概述，SDK 快速入门示例的 HTTP 版本等。
-->

<!--
使用按钮短代码将读者引导到更深入的相关场景，例如 Dapr 教程。
-->

7.3.3 - 操作指南模板

贡献新的操作指南

操作指南为读者提供逐步的实用指导，帮助他们实现以下目标：

• 启用某个功能
• 集成某项技术
• 在特定场景中使用 Dapr

操作指南相较于快速入门，是更高级别的自助文档。操作场景通常需要更长的时间，并且更容易应用于读者的个人项目或环境。

命名操作文档时，应在文件名中包含子目录名称。如果需要创建新的子目录，请确保其具有描述性，并包含相关组件或概念名称。例如，pubsub-namespaces。

了解更多关于贡献 Dapr 文档的信息，例如前置内容和短代码。

模板

---
type: #必填; docs
title: #必填; "如何：简洁明了的标题"
linkTitle: #必填; "如何：比常规标题更短，以便在目录中显示"
weight: #必填; 根据层级使用正确的权重
description: #必填; 对文章内容的期望进行一句话描述
---

<!--
在提交 PR 之前，请删除此模板中的所有注释。
-->

<!-- 
H1：Hugo 前置内容中的标题作为文章的 markdown H1。
-->

<!-- 引言段落  
必填。简要介绍将涵盖的内容以及任何默认的 Dapr 特性。链接到适当的概念或概述文档以提供背景。 -->

<!-- 
如果可能，包含一个图表或图像。
-->

<!--
如果适用，请在短代码注释或警报中链接到相关的快速入门，文本如：

 如果您还没有，请[尝试 <topic> 快速入门](link)，以快速了解如何使用 <topic>。

-->

<!-- 
确保操作指南包含多个编程语言、操作系统或部署目标的示例（如果适用）。
-->

## <操作或任务>

<!-- 
与快速入门不同，不要使用“步骤 1”、“步骤 2”等。
-->

## <操作或任务>

<!-- 
每个 H2 步骤应以动词/动作词开头。
-->

<!--
尽可能包含代码片段。
-->

## 后续步骤

<!--
链接到相关页面和示例。例如，构建块概述、相关教程、API 参考等。
-->