› ›

Logstash 插件社区维护者指南

本文档旨在供新的维护者阅读，解释他们的职责。它受到了 ZeroMQ 项目的 C4 文档的启发。本文档可能会发生更改，强烈建议通过 Pull Requests 和 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 的存储库上工作，并通过创建拉取请求向插件提交补丁。

维护者不得合并作者未签署 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, please test this.”。

插件版本控制

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

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

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

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

更改版本

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

日志记录

尽管重要的是不要因过多的日志记录而降低性能，但调试级别的日志在诊断和解决 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 输出插件编写插件文档 »

Logstash 插件社区维护者指南