« 拉取请求审查指南 为文档做贡献 »
Elastic 文档 ›Beats 开发者指南 [master]

为 Beats 做贡献

编辑

为 Beats 做贡献编辑

如果您有想要贡献的错误修复或新功能，请先在 论坛 上创建一个主题。可能有人已经在处理它了，或者在您实施更改之前应该了解一些特定的问题。

我们乐于与贡献者合作，使他们的代码被接受。解决问题的办法有很多，在编写太多代码之前找到最佳办法很重要。提交代码后，请查看 Elastic 贡献者计划，您可以在其中为您的贡献赚取积分和奖励。

为任何 Elastic 代码库做贡献的过程都类似。

贡献步骤编辑

  1. 请确保您已签署我们的 贡献者许可协议。我们不是要求您将版权转让给我们，而是要求您授予我们无限制分发您的代码的权利。我们要求所有贡献者这样做，以便向我们的用户保证代码的来源和持续存在。您只需要签署一次 CLA。
  2. 发送拉取请求！将您的更改推送到您对代码库的分支，并 提交拉取请求，使用我们的 拉取请求指南。新的 PR 会进入主分支。如果需要，Beats 核心团队会将您的 PR 回滚到其他分支。

在拉取请求中，描述您的更改所做的事情，并提及与拉取请求相关的任何错误/问题。请在 CHANGELOG.next.asciidoc 中添加更改日志条目。

设置您的开发环境编辑

Beats 是 Go 程序，因此请安装 Go 的 1.21.12 版本，该版本用于 Beats 开发。

在 安装 Go 之后，设置 GOPATH 环境变量以指向您的工作区位置，并确保 $GOPATH/bin 位于您的 PATH 中。

使用 GVM Go 版本管理器，可以确定性地安装适用于 Beats 的正确 Go 版本。例如，对于 Mac 用户，命令如下：

gvm use 1.21.12
eval $(gvm 1.21.12)

然后，您可以克隆 Beats Git 代码库

mkdir -p ${GOPATH}/src/github.com/elastic
git clone https://github.com/elastic/beats ${GOPATH}/src/github.com/elastic/beats

如果您有多个 go 路径，请使用 ${GOPATH%%:*} 而不是 ${GOPATH}。

Beats 开发人员主要使用 Mage 进行开发。您可以使用 make 目标安装 mage

make mage

然后，您可以使用 Mage 编译特定的 Beat。例如，对于 Filebeat

cd beats/filebeat
mage build

您可以使用以下命令列出所有可用的 mage 目标

mage -l

某些 Beats 可能具有额外的开发要求，在这种情况下，您会在 Beat 目录中找到一个 CONTRIBUTING.md 文件。

我们在 beats 代码库中使用 EditorConfig 文件来标准化不同编辑器处理文件中的空格、换行符和其他编码样式的方式。大多数流行的编辑器都有 插件 用于 EditorConfig，我们强烈建议您安装它。

更新脚本编辑

Beats 使用各种基于 Python、make 和 mage 的脚本生成配置文件和文档。用于此的主要命令是

make update

每个 Beat 都有自己的 update 目标（对于 make 和 mage 都是如此），以及代码库根目录中的主 update。如果 PR 添加或删除了依赖项，请在根 beats 目录中运行 make update。

另一个命令可以正确格式化 go 源文件并添加版权头

make fmt

这两个命令都应该在提交 PR 之前运行。您可以使用 make help 查看所有可用的 make 目标。

这些命令具有以下依赖项

Python venv 模块包含在 Python 3 的标准库中。在 Debian/Ubuntu 系统上，它还需要安装 python3-venv 软件包，其中包含其他支持脚本

sudo apt-get install python3-venv

选择构建目标编辑

Beats 使用 make release 目标构建。默认情况下，make 会从有限数量的预设构建目标中选择

  • darwin/amd64
  • darwin/arm64
  • linux/amd64
  • windows/amd64

您可以使用 PLATFORMS 环境变量更改构建目标。使用 PLATFORMS 变量设置的目标可以是 GOOS 值，也可以是 GOOS/arch 对。例如，linux 和 linux/amd64 都是有效的目标。您可以选择多个目标，并且 PLATFORMS 列表是用空格分隔的，例如 darwin windows 将在所有受支持的 darwin 和 windows 架构上构建。此外，您可以通过在给定目标前加上 + 或 - 来添加或删除构建目标列表。例如：+bsd 或 -darwin。

您可以使用 go tool dist list 找到所有受支持的构建目标的完整列表。

代码风格检查编辑

Beats 使用 golangci-lint。您可以针对您的更改运行预先配置的代码风格检查程序

mage llc

llc 代表 Lint Last Change，它包括在最后一次提交（如果您在 main 分支上）或在您的功能分支和 main 分支之间的差异中更改的所有 Go 文件。

预计有时会要求贡献者修复与其贡献无关的代码风格检查问题，因为代码风格检查是在某些文件中的更改之后引入的。

您也可以针对单个包运行代码风格检查程序，例如 filbeat 命令包

golangci-lint run ./filebeat/cmd/...

测试编辑

您可以使用以下命令运行整个测试套件

make testsuite

运行测试套件具有以下要求

  • Python >= 3.7
  • Docker >= 1.12
  • Docker-compose >= 1.11

有关更多详细信息，请参阅 测试 指南。

文档编辑

每个 Beat 的主要文档位于 <beatname>/docs 下，基于 AsciiDoc。Beats 文档还广泛使用条件语句和内容重用，以确保一致性和准确性。在为文档做贡献之前，请阅读以下资源

依赖项编辑

为了创建 Beats，我们依赖于 Golang 库和其他外部工具。

其他依赖项编辑

除了 Go 库之外，我们还使用开发工具来生成输入和处理器的解析器。

运行 go generate 需要以下软件包

Auditbeat编辑
  • FlatBuffers >= 1.9
Filebeat编辑
  • Graphviz >= 2.43.0
  • Ragel >= 6.10

更改日志编辑

要了解社区开发者针对官方 Beats 的更改，请关注开发者更改日志 这里。

« 拉取请求审查指南 为文档做贡献 »