SIG 实践（审阅者和维护者）

了解审阅者和维护者如何管理问题和贡献。

本页包含审阅者和维护者使用的指南和一些常见做法。

入职

如果贡献者承担起对文档承担更多责任的角色（审阅者、维护者），他们将由现有的审阅者和维护者进行入职。

  • 他们将被添加到 docs-approvers（或 docs-maintainers）组。
  • 他们将被添加到 #otel-comms 和 #otel-maintainers 私有团队 Slack 频道。
  • 他们将被要求注册 SIG Comms 会议和 维护者会议的日历邀请。
  • 他们将被要求确认当前的 SIG Comms 会议时间是否适合他们，如果不合适，则与现有审阅者和维护者合作，找到一个适合所有人的时间。
  • 他们将被要求审查贡献者可用的各种资源

其他有价值的资源是

协作

  • 审阅者和维护者有不同的工作时间表和情况。因此，所有沟通都假定为异步的，他们不应感到有义务在正常工作时间之外回复。
  • 当审阅者或维护者将在很长一段时间内（超过几天或一周）无法贡献，或在该时间段内无法提供帮助时，他们应使用 #otel-comms 频道并更新 GitHub 状态来传达此事。
  • 审阅者和维护者遵守 OTel 行为准则和 社区价值观。他们对贡献者友好且乐于助人。在发生冲突、误解或任何让审阅者/维护者感到不舒服的情况时，他们可以退出对话、问题或 PR，并要求其他审阅者/维护者介入。

分类

问题

  • 传入的问题由 @open-telemetry/docs-triagers 团队进行分类。
  • 作为第一步，分类员将阅读问题标题和描述，并应用以下标签
    • 必选：sig:*、lang:* 或 docs:* 标签，以确定问题的（共同）所有权
      • 如果问题与内容或由 SIG 共同拥有的问题相关（例如，关于 Collector 的问题将标记为 sig:collector），则标记 sig:*。
      • 如果问题与内容或与特定本地化相关的问题相关，则标记 lang:*。
      • 如果问题与内容或仅由文档团队（SIG Comms）拥有的问题相关，则标记 docs:*。
        • docs
        • docs:admin
        • docs:accessibility
        • docs:analytics-and-seo
        • docs:IA
        • docs:blog
        • docs:cleanup/refactoring
        • docs:upstream、docs:upstream/docsy
        • docs:javascript
        • docs:mobile
        • docs:registry
        • docs:ux
    • 必选：triage:* 标签
      • triage:accepted、triage:accepted:needs-pr
      • triage:deciding、triage:deciding:blocked、triage:deciding:needs-info
      • triage:rejected、triage:rejected:duplicate、triage:rejected:invalid、triage:rejected:wontfix
    • 必选：将问题的“类型”设置为如下
      • 问题类型 bug 用于 bug
      • 问题类型 enhancement 用于功能请求
      • 标签 type:question 用于问题
      • 标签 type:copyedit 用于文字编辑
      • 如果问题似乎是开放式的、无法解决的对话，则将其移动到“讨论区”
    • 可选：如果适用，添加估算标签
      • e0-minutes
      • …
      • e4-months
    • 可选（仅由维护者设置）：优先级标签
      • p0-critical
      • p1-high
      • p2-medium
      • p3-low
    • 可选：以下特殊标签之一
      • good first issue
      • help wanted
      • contribfest
      • maintainers only
      • forever
      • stale
  • 自动化将在 14 天不活动后将 triage:deciding 中的问题标记为 triage:followup 以重新分类。triage:followup 标签应在 7 天内移除。通知参与者和移除标签即为充分的活动。

PR

  • PR 必须有关联的、标记为 triage:accepted 的问题，但有以下例外
    • 自动 PR
    • 维护者/审阅者进行的热修复
  • 自动化将确保 PR 被标记并分配给适当的共同拥有 SIG 或本地化团队。
  • PR 应具有与问题相同的共同所有权标签
  • 如果 PR 由 SIG 共同拥有，该组负责进行首次审查，以确保内容在技术上是正确的。
  • 如果 PR 由语言团队共同拥有，该组负责确保内容的翻译是正确的。
  • 文档团队的主要职责是确保 PR 符合项目的整体目标，放置在结构中的正确位置，并遵循项目的风格和内容指南。
  • 缺少合并条件的 PR 应相应标记
    • missing:cla
    • missing:docs-approval
    • missing:sig-approval
    • blocked
  • 自动化将在 21 天不活动后将 PR 标记为 stale 以请求重新审查。stale 标签应在 14 天内移除。通知参与者和移除标签即为充分的活动。
  • PR 永远不会自动关闭。

代码审查

通用

  • 如果 PR 分支已落后于基础分支，则无需持续更新：每次更新都会触发所有 PR CI 检查！通常在合并前更新就足够了。
  • 非维护者提交的 PR 切勿更新 git 子模块。这种情况偶尔会意外发生。让 PR 作者知道他们不必担心，我们会在合并前修复这个问题，但将来他们应确保从最新的 fork 中工作。
  • 如果贡献者在签署 CLA 时遇到困难，或不小心使用了错误的电子邮件进行提交，请要求他们修复问题或重新变基（rebase）该拉取请求。最坏的情况是，关闭并重新打开 PR 以触发新的 CLA 检查。
  • cspell 未知的单词应由 PR 作者添加到每页的 cspell 忽略列表中。只有审阅者和维护者会添加常用术语到全局列表中。

共同拥有的 PR

由 SIG 共同拥有的文档（collector、demo、语言特定...）的 PR 应争取两次批准：一次由文档审阅者批准，一次由 SIG 审阅者批准。

  • 文档审阅者将此类 PR 标记为 sig:<name> 并在此 PR 上标记 -approvers SIG 组。
  • 在文档审阅者审查并批准 PR 后，他们可以添加 sig-approval-missing 标签。这标志着 SIG 需要处理该 PR。
  • 如果在规定的宽限期内（通常为两周，但紧急情况可能更短）没有获得 SIG 批准，文档维护者可以自行决定合并该 PR。

来自机器人的 PR

可以通过以下方式合并机器人创建的 PR

  • 自动更新注册表中版本的 PR 可以立即修复、批准和合并。
  • 自动更新 SDK、零代码集成或 Collector 版本的 PR 可以批准并合并，除非相应的 SIG 声明应推迟合并。
  • 自动更新任何规范版本的 PR 通常需要更新脚本才能使 CI 检查通过。在这种情况下，@chalin 将处理 PR。否则，除非相应的 SIG 声明应推迟合并，否则这些 PR 也可以批准并合并。

翻译 PR

涉及翻译更改的 PR 应争取两次批准：一次由文档审阅者批准，一次由翻译审阅者批准。与共同拥有的 PR 建议的类似做法适用。

合并 PR

维护者可以通过以下工作流程合并 PR

  • 确保 PR 已获得所有批准且所有 CI 检查均通过。

  • 如果分支已过时，请通过 GitHub UI 进行变基更新。

  • 更新将触发所有 CI 检查重新运行，等待其通过，或执行如下脚本在后台执行此操作

    export PR=<ID OF THE PR>; gh pr checks ${PR} --watch && gh pr merge ${PR} --squash

最后修改于 2025 年 11 月 19 日：[proposal] add triage section to SIG practices (#8431) (6acef014)