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

Logstash 插件社区维护者指南

Logstash 插件社区维护者指南

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

贡献指南

有关为 Logstash 插件贡献代码的一般指南，请参阅 为 Logstash 贡献代码 部分。

文档目标

帮助简化 Logstash 插件社区参与，并提供积极的反馈。

提高多样性。

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

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

将维护者和贡献者的角色和职责编纂成文，重点关注补丁测试、代码审查、合并和发布。

开发工作流

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

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

术语

“贡献者”是指一个人在提供补丁时承担的角色。贡献者将无法访问存储库的提交权限。在审查补丁之前，他们需要签署 Elastic 贡献者许可协议。贡献者可以将自己添加到插件的贡献者列表中。

“维护者”是指一个人在维护插件并保持其健康状态时承担的角色，包括分类 issue 以及审查和合并补丁。

补丁要求

补丁是对一个已识别并达成一致的问题的最小且准确的解答。它必须符合 代码风格指南，并且必须包含验证解决方案有效性的 RSpec 测试。

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

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

补丁提交消息的第一行是一个简短的（少于 50 个字符）总结更改的句子，第二行为空行，如有必要，后续行可以提供更改的说明和理由。

当补丁满足上述要求并至少获得另一人的积极审查时，即可合并。

开发流程

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

要处理 issue，贡献者需要 fork 插件存储库，然后在他们的 fork 存储库上进行工作，并通过创建 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 输出插件 为您的插件编写文档 »