Logstash 插件社区维护者指南

本文档供新维护者阅读，应解释他们的职责。它受到 ZeroMQ 项目的 C4 文档的启发。本文档可能会发生变化，强烈建议通过 Pull Request 和 issue 提出建议。

有关为 Logstash 插件做出贡献的一般指导，请参阅为 Logstash 做贡献部分。

为了让 Logstash 插件社区参与变得容易，并获得积极的反馈。

增加多样性。

通过向社区和维护者提供支持和工具，减少核心团队对代码审查、合并和发布的依赖。

支持插件的自然生命周期。

明确维护者和贡献者的角色和职责：特别关注补丁测试、代码审查、合并和发布。

所有 Issue 和 Pull Request 必须使用 Github issue 跟踪器进行跟踪。

该插件使用 Apache 2.0 许可证。维护者应检查补丁是否引入了具有不兼容许可证的代码。补丁的所有权和版权在 Elastic 贡献者许可协议 (CLA) 中定义。

“贡献者”是指在提供补丁时，某个人所扮演的角色。贡献者将没有提交到存储库的权限。他们需要签署 Elastic 贡献者许可协议，然后才能审查补丁。贡献者可以将自己添加到插件贡献者列表中。

“维护者”是指维护插件并使其保持健康状态的人员所扮演的角色，包括分类 issue 以及审查和合并补丁。

补丁是对明确的一个已识别和商定的问题，给出的最小且准确的答案。它必须符合代码风格指南，并且必须包括 RSpec 测试，以验证解决方案的适用性。

补丁将由 CI 系统自动测试，该系统将报告 Pull Request 状态。

补丁 CLA 将被自动验证，并在 Pull Request 状态中报告。

补丁提交消息的第一行应该是一个简短的摘要（少于 50 个字符），第二行是空行，其余行根据需要用于解释变更和原因。

当补丁满足上述要求并且已被至少一个人正面审查时，它才是可合并的。

用户将在 issue 跟踪器上记录一个 issue，尽可能详细地描述他们面临的问题或观察到的问题。

要处理一个 issue，贡献者 fork 插件存储库，然后在他们 fork 的存储库上工作，并通过创建 pull request 将补丁提交回插件。

维护者不得合并作者未签署 CLA 的补丁。

在接受补丁之前，应进行审查。维护者应毫不拖延地合并已接受的补丁。

维护者不应合并他们自己的补丁，除非在特殊情况下，例如其他维护者或核心团队长时间（超过 2 周）未响应。

审查者的评论不应基于个人偏好。

维护者应标记 Issue 和 Pull Request。

如果需要帮助才能达成共识，维护者应让核心团队参与。

以与源代码更改相同的方式审查非源代码更改，例如文档。

该插件有一个主分支，始终保存最新的正在开发版本，并且应该始终构建。主题分支应保持在最低限度。

每个插件都应该有一个更新日志 (https://elastic.ac.cn/guide/en/logstash/current/CHANGELOG.html)。如果没有，请创建一个。当对插件进行更改时，请务必在相应版本下包含一个更新日志条目，以记录更改。从用户的角度来看，更新日志应该易于理解。当我们快速迭代和发布插件时，用户使用更新日志作为决定是否更新的机制。

非面向用户的更改应标记为 internal:。例如

- internal: Refactored specs for better testing
- config: Default timeout configuration changed from 10s to 5s

在插件中共享与 https://elastic.ac.cn/guide/en/logstash/current/CHANGELOG.html 类似的格式，可以方便用户的阅读。请参见以下带注释的示例，并在logstash-filter-date中查看具体示例。

## 1.0.x
 - change description
 - tag: change description
 - tag1,tag2: change description
 - tag: Multi-line description
   must be indented and can use
   additional markdown syntax
                                      <6>
## 1.0.0
[...]

1. 最新版本是 https://elastic.ac.cn/guide/en/logstash/current/CHANGELOG.html 的第一行。每个版本标识符都应该是一个使用 ## 的二级标题
2. 一个更改描述被描述为一个列表项，使用一个破折号 - 在版本标识符下对齐
3. 一个更改可以通过一个单词标记，并加上后缀 :。
   常见的标签有 bugfix、feature、doc、test 或 internal。
4. 一个更改可以有多个标签，用逗号分隔，并加上后缀 :
5. 多行更改描述必须正确缩进
6. 请注意用空行分隔版本
7. 先前版本标识符

插件已设置了自动持续集成 (CI) 环境，并且每个 Github 页面上都应该有一个对应的徽章。如果缺少，请联系 Logstash 核心团队。

打开的每个 Pull Request 都会自动触发 CI 运行。要执行手动运行，请在 Pull Request 上评论“Jenkins, please test this.”。

Logstash 核心及其插件具有单独的产品开发生命周期。因此，核心和插件的版本控制和发布策略不必对齐。事实上，这是我们在 Logstash 1.5 中进行插件大分离工作期间的目标之一。

有时，Logstash 核心 API 会发生变化，这将需要大规模更新插件以反映核心中的更改。但是，这种情况并不经常发生。

对于插件，我们希望遵守一种版本控制和发布策略，该策略可以更好地告知我们的用户有关 Logstash 配置格式和功能的任何重大更改。

插件发布遵循三位数字方案 X.Y.Z。其中 X 表示可能破坏与现有配置或功能的兼容性的主要版本。Y 表示包含向后兼容功能的版本。Z 表示包含错误修复和补丁的版本。

可以在 Gemspec 中更改版本，这需要与更新日志条目相关联。之后，我们可以手动将 gem 发布到 RubyGem.org。目前，只有核心开发人员可以发布 gem。

标记是维护插件的关键方面。GitHub 中的所有 issue 都应正确标记，以便它可以

• 向用户/开发人员提供良好的反馈
• 帮助确定变更的优先级
• 在发行说明中使用

大多数标签是不言自明的，但这里简要回顾一下一些重要的标签

• bug：将 issue 标记为意外缺陷
• needs details：如果 issue 报告者提供的详细信息不完整，请向他们索取更多信息并标记为需要详细信息。
• missing cla：缺少贡献者许可协议，没有它，补丁将无法接受
• adopt me：请求社区帮助接管此 issue
• enhancement：新功能，不是错误修复
• needs tests：补丁没有测试，没有单元/集成测试就无法接受
• docs：与文档相关的 issue/PR

虽然重要的是不要因过度日志记录而降低性能，但调试级别日志在诊断和解决 Logstash 问题时可能非常有用。请记住，只要有意义，就应自由添加调试日志，因为用户将永远感激。

@logger.debug("Logstash loves debug logs!", :actions => actions)

为什么需要CLA？

我们需要所有贡献者都签署 CLA，以确保我们的用户了解代码的来源和持续存在。我们不是要求贡献者将版权转让给我们，而是给予我们无限制分发贡献者代码的权利。

请确保在审查 PR 和提交之前，每个贡献者都已签署 CLA。

贡献者只需签署一次 CLA，并且应使用与 Github 中使用的相同的电子邮件进行签名。如果贡献者在提交 PR 后签署 CLA，他们可以在签署后 5 分钟后通过在 PR 上推送另一个评论来刷新自动 CLA 检查器。

在 Github 上 Ping @logstash-core，以引起 Logstash 核心团队的注意。

核心团队负责支持插件维护者和整个生态系统。

维护者应提名贡献者成为维护者。

贡献者和维护者应遵守 Elastic 社区行为准则。核心团队应阻止或禁止“不良行为者”。