贡献文档

Beats 文档采用 Markdown 编写，并使用 elastic/docs-builder 构建。

从 Elastic Stack 9.0.0 版本开始，我们不再为每个次要版本发布一套新的文档。这意味着单个页面应能长期有效，并使用与版本相关的标签来说明产品的发展演变。

有关如何为手动维护的内容标注产品生命周期和版本信息的信息，请参阅 编写累积式文档。

有关自动生成的内容，请阅读 更新 fields.yml 以了解更多信息。

Beats 仓库中的许多 Markdown 文件应直接编辑，但有些文件是自动生成的，包括：

• 导出的字段（例如，AWS 字段）
• 模块文档（例如，AWS 模块）
• 指标集（Metricset）和数据集（Dataset）文档（例如，AWS 账单指标集）

各个 Beats 中 _meta 目录下的 fields.yml 文件包含模块、数据集、文件集或指标集中可用字段的描述。以下是优化 fields.yml 以生成文档的一些建议：

• title 用作文档中的页面标题，因此最好将其首字母大写。

• 各层级的 description 应使用完整的句子书写，并包含标点符号。

• 各层级的 version 用于标注文档的产品生命周期和与版本相关的信息，以说明产品随时间的发展演变，这对编写累积式文档非常重要。以下是使用 version 的一些建议：

  • 支持的产品生命周期包括 preview（预览版）、 beta（测试版）、 ga（正式版）和 deprecated（已弃用）。
  • 同一个模块或字段可以存在多个产品生命周期，以说明它随时间的变化。
  • 版本号可以是主版本、次版本或补丁版本格式，但最终渲染的标签始终会解析到补丁级别。
  • 以下是经历过所有产品生命周期的字段的 version 示例：

    version:
      preview: 9.0.0
      beta: 9.1.0
      ga: 9.2.0
      deprecated: 9.3.0
    		

_meta 目录中的 docs.md 文件用于生成模块文档。

更新 _meta 目录中的 fields.yml 和 docs.md 文件后，必须运行文档收集器脚本来重新生成文档

1. 请确保您设置了 Beats 开发环境并使用了正确的 Go 版本。

   • Go 版本列在您想要更新的分支的 version.asciidoc 文件中。

2. 切换到 beats 仓库目录。

3. 运行 make update 以执行文档收集器脚本。

   警告

   make update 命令会不带警告地覆盖 docs 目录中的文件。如果您不小心更新了生成的文件并运行了 make update，您的更改将被覆盖。

   make 命令调用以下脚本来生成文档

   • auditbeat/scripts/mage/docs.go 生成
     • docs/reference/auditbeat/auditbeat-modules.md
     • docs/reference/auditbeat/auditbeat-module-*.md
   • filebeat/scripts/mage/docs.go 生成
     • docs/reference/filebeat/filebeat-modules.md
     • docs/reference/filebeat/filebeat-module-*.md
   • metricbeat/scripts/mage/docs_collector.go 生成
     • docs/reference/metricbeat/metricbeat-modules.md
     • docs/reference/metricbeat/metricbeat-module-*.md
   • dev-tools/mage/generate_fields_docs.go 生成
     • docs/reference/auditbeat/exported-fields.md
     • docs/reference/filebeat/exported-fields.md
     • docs/reference/heartbeat/exported-fields.md
     • docs/reference/metricbeat/exported-fields.md
     • docs/reference/packetbeat/exported-fields.md
     • docs/reference/winlogbeat/exported-fields.md

4. （可选）要格式化您的文件，您可能还需要运行此命令

   make fmt