« 如何编写 Logstash 输出插件 为您的插件编写文档 »
Elastic 文档 ›Logstash 参考 [8.14] ›为 Logstash 做贡献

Logstash 插件社区维护者指南

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 插件存储库，然后在他们的 forked 存储库上进行工作，并通过创建 Pull Request 回到插件来提交补丁。

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

在补丁被接受之前，它应该被审查。维护者应尽快合并已接受的补丁。

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

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

维护者应为 Issue 和 Pull Request 添加标签。

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

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

分支管理

该插件有一个主分支，它始终包含最新的进行中的版本，并且应该始终构建。主题分支应保持最少。

变更日志管理

每个插件都应该有一个变更日志 (CHANGELOG.md)。如果没有，请创建一个。当对插件进行更改时，请确保在相应的版本下包含一个变更日志条目来记录更改。变更日志应该从用户的角度易于理解。由于我们快速迭代和发布插件，用户使用变更日志来决定是否更新。

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

 - internal: Refactored specs for better testing
 - config: Default timeout configuration changed from 10s to 5s
CHANGELOG.md 的详细格式

在插件中共享类似的 CHANGELOG.md 格式可以方便用户阅读。请参阅以下带注释的示例，并在 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
                                      
## 1.0.0                              
[...]

最新版本是 CHANGELOG.md 的第一行。每个版本标识符都应该是一个使用 ## 的二级标题。

一个更改描述被描述为一个使用短划线 - 对齐在版本标识符下的列表项。

一个更改可以用一个单词标记，并在后面加上 :。
常见的标签有 bugfix、feature、doc、test 或 internal。

一个更改可以有多个标签，用逗号分隔，并在后面加上 :。

多行更改描述必须正确缩进。

请注意 用空行分隔版本

以前的版本标识符

持续集成

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

每个打开的 Pull Request 都会自动触发 CI 运行。要进行手动运行，请在 Pull Request 中评论“Jenkins，请测试一下”。

版本控制插件

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 报告者提供的详细信息不完整，请要求他们提供更多信息并标记为 needs details。
  • missing cla: 缺少贡献者许可协议，没有它补丁无法被接受
  • adopt me: 请求社区帮助接手此 Issue
  • enhancement: 新功能，不是错误修复
  • needs tests: 补丁没有测试，没有单元/集成测试无法被接受
  • docs: 与文档相关的 Issue/PR

日志记录

虽然避免因过度日志记录而降低性能很重要，但调试级别日志在诊断和解决 Logstash 问题时非常有用。请记住，在有意义的地方自由添加调试日志，因为用户会永远感激您。

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

贡献者许可协议 (CLA) 指南

1.

为什么需要 CLA？

我们要求所有贡献者这样做，以确保我们的用户了解代码的来源和持续存在。我们并没有要求贡献者将版权转让给我们，而是要求他们授予我们不受限制地分发贡献者代码的权利。

2.

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

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

需要帮助？

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

社区管理

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

维护者应该提议贡献者成为维护者。

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

« 如何编写 Logstash 输出插件 为您的插件编写文档 »