Vector 项目文档编写与维护实战指南从 CUE 参考文档生成到 Changelog 与 Release Highlights【免费下载链接】vectorA high-performance observability data pipeline.项目地址: https://gitcode.com/GitHub_Trending/vect/vector本指南以 Vector高性能可观测性数据管道仓库中的 docs/DOCUMENTING.md 为主体系统讲解贡献者在提交代码时如何同步维护官方文档包括以 CUE 结构化数据驱动的参考文档体系、从 Rust 配置模式自动生成组件文档、格式化与 CI 校验流程、Changelog 片段规范以及 Release Highlights 的编写标准。读完本文你将掌握在 Vector 仓库中为新的 source/sink/transform 添加完整文档的端到端工作流并理解底层构建工具链Makefile、scripts/cue.sh、vdev的实际运行机制。一、贡献者的文档职责边界文档对 Vector 项目至关重要。作为贡献者你在提交代码的同时有责任同步维护以下用户侧体验相关的内容参考文档变更位于 website/cue 目录通常是配置项变更既有指南变更位于 website/content 目录Release Highlights视相关性位于 website/content/en/highlights 目录用于未来版本的发布说明。而默认情况下你不负责的事项包括为你的改动撰写全新指南除非被指派、撰写博客文章除非被指派。这种代码与文档强耦合的约定保证了每个配置参数、每个组件行为的变化都能及时反映到官方文档中避免文档与实现脱节。二、参考文档体系CUE 驱动的数据化文档Vector 的参考文档是面向所有 Vector 内容的索引例如其中包含 Vector 配置可用选项的完整清单。它是高度数据驱动的因此由 website/cue 目录中定义的结构化数据来承载。CUEcuelang.org是一种声明式配置语言非常适合复杂数据定义场景。在 Vector 中CUE 文件不仅描述组件的元数据标题、描述、特性分类、示例还通过引用自动生成的配置 schema 来保证文档与 Rust 源码的一致性。从仓库结构看website/cue/reference/components 下按sources、sinks、transforms三个目录组织组件文档其中generated/子目录存放从 Rust 配置模式自动生成的 CUE 文件手工编写的 CUE 文件如 website/cue/reference/components/transforms/remap.cue补充标题、描述、示例、特性分类、how-it-works 等无法自动生成的元数据。以remap.cue为例它声明了组件的title、description、classes开发状态、输出方式、是否有状态、input/output支持的事件类型、examples、how_it_works章节以及额外的dropped输出其中配置主体直接引用generated.components.transforms.remap.configuration实现了源码即文档。2.1 安装 CUECUE 可以通过包管理器安装但为了使用 Vector 依赖的正确版本可能需要从源码安装。当前 Vector 使用的 CUE 版本是v0.7.0。使用不同版本的 CUE 可能导致 CUE check/build 报错。2.2 从源码生成参考文档Vector 的大量参考文档是从源码例如 doc comments自动编译生成的。重新生成这些内容的命令make generate-docs从 Makefile 可以看到generate-docs是一个聚合目标它依次执行generate-docs: generate-component-docs generate-vector-vrl-docs generate-vrl-docs generate-example-configs即组件文档生成、VRL 函数文档生成写入 docs/generated、网站侧 VRL 文档生成、组件示例配置生成。2.3 generate-schemaJSON Schema 生成器generate-component-docsMakefile的底层实现值得关注——它先编译 Vector然后运行vector generate-schema命令将整个配置结构导出为 JSON Schema。该命令的实现位于 src/generate_schema.rs通过vector_lib::configurable::schema::generate_root_schema::ConfigBuilder()基于配置结构体的属性如默认值、注释、校验规则递归生成 root schema支持--output-path参数写入文件未指定时直接打印到 stdout。# generate-component-docs 的完整执行链路摘自 Makefile cargo build $(CARGO_TARGET_DIR)/debug/vector generate-schema /tmp/vector-config-schema.json $(VDEV) build component-docs /tmp/vector-config-schema.json ./scripts/cue.sh fmt这一链路说明配置参数的文档行为说明应写在 Rust 的 doc comments 中生成命令会把它们填充进 CUE 文件。三、为新增组件添加文档六步完整流程当引入一个新的 source、sink 或 transform 时需要按以下两步/六步完成文档创建第 1 步生成基础文档make generate-component-docs这会在website/cue/reference/components/{sources,sinks,transforms}/generated/component_name.cue生成一个自动生成的 CUE 文件包含来自 Rust 代码的全部配置选项。配置参数的行为说明应写入 Rust 文档注释上述命令会生成填充了 Rust 文档的 CUE 文件。第 2 步创建手工 CUE 文件在website/cue/reference/components/{sources,sinks,transforms}/component_name.cue新建文件补充无法自动生成的元数据包括title、description示例examples特性分类classes、featureshow-it-works 章节how_it_works可以参考现有组件的写法例如 website/cue/reference/components/transforms/remap.cue。该文件中how_it_works章节的写法非常典型remap_language、event_data_model、lazy_event_mutation、emitting_multiple_events等小节分别用titlebody支持 CUE 多行字符串与#原始字符串描述一个概念要点例如惰性事件修改解释了 VRL 路径赋值不会立即生效、程序失败时改动会被丢弃的行为并提示可用drop_on_error配置丢弃失败事件。第 3 步格式化 CUE 文件./scripts/cue.sh fmt第 4 步为网站创建 Markdown 文档在website/content/en/docs/reference/configuration/{sources,sinks,transforms}/component_name.md新建 Markdown 文件参考已有示例例如 website/content/en/docs/reference/configuration/transforms/remap.md。第 5 步验证文档正确性make check-generated-docs该目标Makefile依赖generate-docs重新生成所有文档再通过$(VDEV) check generated-docs和$(VDEV) check component-examples检查机器生成的组件文档与示例是否与当前代码一致即是否有未提交的生成差异。第 6 步本地预览渲染效果建议进入网站目录启动本地开发服务器查看文档在 Vector 网站上的实际渲染效果cd website make serve从 website/Makefile 可见make serve会先执行clean、setup、cargo-data、structured-data生成 VRL 文档、弃用说明 JSON、组件示例随后用 Hugo 以 development 环境启动本地服务默认绑定127.0.0.1端口1313可通过SERVER_BIND/SERVER_PORT环境变量覆盖并联动 pagefind 建立站点内搜索索引。四、CUE 格式化scripts/cue.sh 深入解析Vector 对docs目录的改动有一系列 CI 检查其中就包括确保 CUE 源码格式正确。执行 CUE 自动格式化的命令在 vector 仓库根目录./scripts/cue.sh fmt如果该命令重写了任何文件务必提交这些变更否则 CI 会失败。从 scripts/cue.sh 的实现看cmd_fmt会列出 website/cue 下所有*.cue文件并排除reference/remap/functions/目录该目录是从 VRL 源码生成的 JSON 风格 CUE 文件不应被 CUE formatter 重排然后对剩余文件逐个执行cue fmt。该脚本还提供了其他实用子命令子命令作用build将全部 CUE 源码导出为 Hugo 可处理的 JSON 对象website/data/docs.jsoncheck检查 CUE 源码的正确性fmt用内置 formatter 格式化所有 CUE 文件list列出所有文档文件vet检查文档文件并打印错误eval打印求值后的文档可用-e EXPRESSION指定表达式export导出文档可用-e EXPRESSION指定表达式例如查看components.sources.kubernetes_logs子树./scripts/cue.sh eval -e components.sources.kubernetes_logs以 JSON 格式导出cli子树./scripts/cue.sh export -e cli五、校验 CUE 有效性make check-docs除了格式正确CUE 源码还必须有效即提供的数据需符合各种 CUE schema。校验命令cd .. # 切换到仓库根目录 CItrue make check-docs当 CI 标志开启时检查器还会额外执行 CUE 格式校验步骤。另外注意该标志开启时 CUE 文件可能会被修改详见scripts/check-docs.sh。从 Makefile 看check-docs依赖generate-vrl-docs因为组件文档引用了remap.functions.*随后执行$(VDEV) check docs。而 scripts/check-docs.sh 揭示了底层校验的两个阶段格式校验先运行cue.sh fmt原地修改文件再用git diff --name-only检测 website/cue 下是否有文件被改写若有则列出未格式化文件并提示运行./scripts/cue.sh fmt修复随后以非零退出码失败。正确性校验执行cue.sh vet即cue vet --concrete --all-errors对全部 CUE 文件做并发且聚合所有错误的类型检查。5.1 实战技巧小步增量 保存即校验编写 CUE 的良好实践是做小而增量的修改并频繁检查变更是否有效。一次性引入多个错误的大改动往往会面对 CUE 冗长且不总是很有帮助的日志输出难以定位问题。推荐使用 watchexec 这类工具在每次保存时自动触发校验# 在仓库根目录 watchexec make check-docs六、Changelog用 fragment 记录用户可见变更贡献者通过在 changelog.d 下添加 fragment 来记录用户可见的变更在发布准备阶段cargo vdev release prepare会把这些 fragment 组装进 release CUE 文件的用户可见 changelog 章节。详细约定见 changelog.d/README.md。6.1 fragment 何时必需当变更对用户可观察改变行为、配置、输出格式、性能或安全态势时必须添加 fragment仅内部改动无行为变化的重构、CI/测试工具、纯文档、不影响行为的依赖升级可跳过并打上no-changelog标签。6.2 文件命名与类型fragment 的命名格式为unique_name.fragment_type.md文件名必须恰好包含两个句点分隔名称、类型和扩展名。合法类型由vdev changelog types定义类型含义breaking与旧版本不兼容、需要用户调整的变更若同时是 fix 或 featurebreaking 优先security有安全影响的变更feature引入新功能的变更enhancement以用户可感知方式增强现有功能的变更fix修复 bug 的变更仓库中真实存在的示例包括 changelog.d/24410_aggregate_event_time_aggregation.feature.md、changelog.d/25723_grpc_decompression_error_detail.fix.md 等文件名直接体现了issue号_描述.类型.md的约定。6.3 内容编写要点内容必须是合法 Markdown且渲染为 changelog 列表中的单个列表项——因此避免使用标题语法分隔内容否则会成为主 changelog 中的标题改用换行分隔。一个好的 fragment 回答三个问题① 该变更如何影响用户可见行为② 影响哪些组件③ 引入或影响了哪些配置字段最后必须以authors:行结尾多个作者用空格分隔不要加前缀。breaking类型的 fragment 带有额外结构化字段H1 标题可含 Hugo 风格的{#anchor}锚点、## Summary和## Migration章节发布流程可据此自动生成升级指南纯告知型 breaking 的## Migration写N/A。推荐使用脚手架命令创建 fragment自动填写文件名、结构与作者行vdev changelog new fix 42_kafka_ack_race vdev changelog new enhancement retry_backoff_config vdev changelog new breaking env_var_interpolation并用vdev check changelog-fragments以与 CI 相同的方式校验校验文件名格式、authors:行以及 breaking fragment 的## Summary/## Migration结构。七、Release Highlights发布说明中的高价值变更由于 Vector 的发布往往包含大量变更项目使用 highlights 来突出高价值、有意义的变更。Highlights 是位于 website/content/en/highlights 目录下的 Markdown 文件精心描述一个特性每个 highlight 都会在相应的发布说明中显著展示。仓库中此类文件按YYYY-MM-DD-描述.md命名如2020-09-18-adaptive-concurrency等。7.1 FAQ什么值得写 Highlight什么样的 release highlight 才算值得写它应当为用户提供实际价值。这本质上是主观判断无法定义精确规则但要警惕产出低价值 highlight 而稀释其含义。通常一次发布不超过6 个highlights。7.2 FAQHighlight 与博客文章的区别Highlights 不是博客文章。它们是简短的一到两段式公告如果相关可以暗示或链接到更深入的博客文章。例如 adaptive concurrency自适应并发的公告本身值得写 highlight但这项带来性能和可靠性收益的工作同样值得一篇深入剖析的博客文章。八、文档工作流总览将以上流程串起来一个完整的文档维护闭环如下Rust 配置源码doc comments / schema 属性 │ make generate-component-docsvector generate-schema → JSON Schema → CUE ▼ website/cue/reference/components/{sources,sinks,transforms}/generated/name.cue │ 手工 CUE 文件标题、示例、how_it_works 等元数据 ▼ ./scripts/cue.sh fmt格式化 → CItrue make check-docs格式 vet 校验 │ ▼ website/content/en/docs/reference/configuration/{sources,sinks,transforms}/name.md网站页面 │ ▼ cd website make serve本地预览 → make check-generated-docsCI 一致性 │ ▼ changelog.d/name.type.md记录用户可见变更→ website/content/en/highlights/可选高价值特性这套体系的核心价值在于用 CUE 把源码文档与网站呈现连接起来——配置参数说明来自 Rust 注释、组件元数据由人工维护、生成结果经过 formatter 与 schema 双重校验从而保证官方文档始终与代码实现保持同步而 Changelog fragment 与 Release Highlights 则构成了面向用户的变更叙事层。相关资源docs/DOCUMENTING.md本文主体来源website/cueCUE 参考文档源码website/content/en/highlightsRelease Highlightschangelog.d/README.mdChangelog fragment 规范scripts/cue.sh 与 scripts/check-docs.shCUE 工具链src/generate_schema.rsgenerate-schema 命令实现website/cue/reference/components/transforms/remap.cue手工 CUE 文件示例【免费下载链接】vectorA high-performance observability data pipeline.项目地址: https://gitcode.com/GitHub_Trending/vect/vector创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Vector 项目文档编写与维护实战指南：从 CUE 参考文档生成到 Changelog 与 Release Highlights
Vector 项目文档编写与维护实战指南从 CUE 参考文档生成到 Changelog 与 Release Highlights【免费下载链接】vectorA high-performance observability data pipeline.项目地址: https://gitcode.com/GitHub_Trending/vect/vector本指南以 Vector高性能可观测性数据管道仓库中的 docs/DOCUMENTING.md 为主体系统讲解贡献者在提交代码时如何同步维护官方文档包括以 CUE 结构化数据驱动的参考文档体系、从 Rust 配置模式自动生成组件文档、格式化与 CI 校验流程、Changelog 片段规范以及 Release Highlights 的编写标准。读完本文你将掌握在 Vector 仓库中为新的 source/sink/transform 添加完整文档的端到端工作流并理解底层构建工具链Makefile、scripts/cue.sh、vdev的实际运行机制。一、贡献者的文档职责边界文档对 Vector 项目至关重要。作为贡献者你在提交代码的同时有责任同步维护以下用户侧体验相关的内容参考文档变更位于 website/cue 目录通常是配置项变更既有指南变更位于 website/content 目录Release Highlights视相关性位于 website/content/en/highlights 目录用于未来版本的发布说明。而默认情况下你不负责的事项包括为你的改动撰写全新指南除非被指派、撰写博客文章除非被指派。这种代码与文档强耦合的约定保证了每个配置参数、每个组件行为的变化都能及时反映到官方文档中避免文档与实现脱节。二、参考文档体系CUE 驱动的数据化文档Vector 的参考文档是面向所有 Vector 内容的索引例如其中包含 Vector 配置可用选项的完整清单。它是高度数据驱动的因此由 website/cue 目录中定义的结构化数据来承载。CUEcuelang.org是一种声明式配置语言非常适合复杂数据定义场景。在 Vector 中CUE 文件不仅描述组件的元数据标题、描述、特性分类、示例还通过引用自动生成的配置 schema 来保证文档与 Rust 源码的一致性。从仓库结构看website/cue/reference/components 下按sources、sinks、transforms三个目录组织组件文档其中generated/子目录存放从 Rust 配置模式自动生成的 CUE 文件手工编写的 CUE 文件如 website/cue/reference/components/transforms/remap.cue补充标题、描述、示例、特性分类、how-it-works 等无法自动生成的元数据。以remap.cue为例它声明了组件的title、description、classes开发状态、输出方式、是否有状态、input/output支持的事件类型、examples、how_it_works章节以及额外的dropped输出其中配置主体直接引用generated.components.transforms.remap.configuration实现了源码即文档。2.1 安装 CUECUE 可以通过包管理器安装但为了使用 Vector 依赖的正确版本可能需要从源码安装。当前 Vector 使用的 CUE 版本是v0.7.0。使用不同版本的 CUE 可能导致 CUE check/build 报错。2.2 从源码生成参考文档Vector 的大量参考文档是从源码例如 doc comments自动编译生成的。重新生成这些内容的命令make generate-docs从 Makefile 可以看到generate-docs是一个聚合目标它依次执行generate-docs: generate-component-docs generate-vector-vrl-docs generate-vrl-docs generate-example-configs即组件文档生成、VRL 函数文档生成写入 docs/generated、网站侧 VRL 文档生成、组件示例配置生成。2.3 generate-schemaJSON Schema 生成器generate-component-docsMakefile的底层实现值得关注——它先编译 Vector然后运行vector generate-schema命令将整个配置结构导出为 JSON Schema。该命令的实现位于 src/generate_schema.rs通过vector_lib::configurable::schema::generate_root_schema::ConfigBuilder()基于配置结构体的属性如默认值、注释、校验规则递归生成 root schema支持--output-path参数写入文件未指定时直接打印到 stdout。# generate-component-docs 的完整执行链路摘自 Makefile cargo build $(CARGO_TARGET_DIR)/debug/vector generate-schema /tmp/vector-config-schema.json $(VDEV) build component-docs /tmp/vector-config-schema.json ./scripts/cue.sh fmt这一链路说明配置参数的文档行为说明应写在 Rust 的 doc comments 中生成命令会把它们填充进 CUE 文件。三、为新增组件添加文档六步完整流程当引入一个新的 source、sink 或 transform 时需要按以下两步/六步完成文档创建第 1 步生成基础文档make generate-component-docs这会在website/cue/reference/components/{sources,sinks,transforms}/generated/component_name.cue生成一个自动生成的 CUE 文件包含来自 Rust 代码的全部配置选项。配置参数的行为说明应写入 Rust 文档注释上述命令会生成填充了 Rust 文档的 CUE 文件。第 2 步创建手工 CUE 文件在website/cue/reference/components/{sources,sinks,transforms}/component_name.cue新建文件补充无法自动生成的元数据包括title、description示例examples特性分类classes、featureshow-it-works 章节how_it_works可以参考现有组件的写法例如 website/cue/reference/components/transforms/remap.cue。该文件中how_it_works章节的写法非常典型remap_language、event_data_model、lazy_event_mutation、emitting_multiple_events等小节分别用titlebody支持 CUE 多行字符串与#原始字符串描述一个概念要点例如惰性事件修改解释了 VRL 路径赋值不会立即生效、程序失败时改动会被丢弃的行为并提示可用drop_on_error配置丢弃失败事件。第 3 步格式化 CUE 文件./scripts/cue.sh fmt第 4 步为网站创建 Markdown 文档在website/content/en/docs/reference/configuration/{sources,sinks,transforms}/component_name.md新建 Markdown 文件参考已有示例例如 website/content/en/docs/reference/configuration/transforms/remap.md。第 5 步验证文档正确性make check-generated-docs该目标Makefile依赖generate-docs重新生成所有文档再通过$(VDEV) check generated-docs和$(VDEV) check component-examples检查机器生成的组件文档与示例是否与当前代码一致即是否有未提交的生成差异。第 6 步本地预览渲染效果建议进入网站目录启动本地开发服务器查看文档在 Vector 网站上的实际渲染效果cd website make serve从 website/Makefile 可见make serve会先执行clean、setup、cargo-data、structured-data生成 VRL 文档、弃用说明 JSON、组件示例随后用 Hugo 以 development 环境启动本地服务默认绑定127.0.0.1端口1313可通过SERVER_BIND/SERVER_PORT环境变量覆盖并联动 pagefind 建立站点内搜索索引。四、CUE 格式化scripts/cue.sh 深入解析Vector 对docs目录的改动有一系列 CI 检查其中就包括确保 CUE 源码格式正确。执行 CUE 自动格式化的命令在 vector 仓库根目录./scripts/cue.sh fmt如果该命令重写了任何文件务必提交这些变更否则 CI 会失败。从 scripts/cue.sh 的实现看cmd_fmt会列出 website/cue 下所有*.cue文件并排除reference/remap/functions/目录该目录是从 VRL 源码生成的 JSON 风格 CUE 文件不应被 CUE formatter 重排然后对剩余文件逐个执行cue fmt。该脚本还提供了其他实用子命令子命令作用build将全部 CUE 源码导出为 Hugo 可处理的 JSON 对象website/data/docs.jsoncheck检查 CUE 源码的正确性fmt用内置 formatter 格式化所有 CUE 文件list列出所有文档文件vet检查文档文件并打印错误eval打印求值后的文档可用-e EXPRESSION指定表达式export导出文档可用-e EXPRESSION指定表达式例如查看components.sources.kubernetes_logs子树./scripts/cue.sh eval -e components.sources.kubernetes_logs以 JSON 格式导出cli子树./scripts/cue.sh export -e cli五、校验 CUE 有效性make check-docs除了格式正确CUE 源码还必须有效即提供的数据需符合各种 CUE schema。校验命令cd .. # 切换到仓库根目录 CItrue make check-docs当 CI 标志开启时检查器还会额外执行 CUE 格式校验步骤。另外注意该标志开启时 CUE 文件可能会被修改详见scripts/check-docs.sh。从 Makefile 看check-docs依赖generate-vrl-docs因为组件文档引用了remap.functions.*随后执行$(VDEV) check docs。而 scripts/check-docs.sh 揭示了底层校验的两个阶段格式校验先运行cue.sh fmt原地修改文件再用git diff --name-only检测 website/cue 下是否有文件被改写若有则列出未格式化文件并提示运行./scripts/cue.sh fmt修复随后以非零退出码失败。正确性校验执行cue.sh vet即cue vet --concrete --all-errors对全部 CUE 文件做并发且聚合所有错误的类型检查。5.1 实战技巧小步增量 保存即校验编写 CUE 的良好实践是做小而增量的修改并频繁检查变更是否有效。一次性引入多个错误的大改动往往会面对 CUE 冗长且不总是很有帮助的日志输出难以定位问题。推荐使用 watchexec 这类工具在每次保存时自动触发校验# 在仓库根目录 watchexec make check-docs六、Changelog用 fragment 记录用户可见变更贡献者通过在 changelog.d 下添加 fragment 来记录用户可见的变更在发布准备阶段cargo vdev release prepare会把这些 fragment 组装进 release CUE 文件的用户可见 changelog 章节。详细约定见 changelog.d/README.md。6.1 fragment 何时必需当变更对用户可观察改变行为、配置、输出格式、性能或安全态势时必须添加 fragment仅内部改动无行为变化的重构、CI/测试工具、纯文档、不影响行为的依赖升级可跳过并打上no-changelog标签。6.2 文件命名与类型fragment 的命名格式为unique_name.fragment_type.md文件名必须恰好包含两个句点分隔名称、类型和扩展名。合法类型由vdev changelog types定义类型含义breaking与旧版本不兼容、需要用户调整的变更若同时是 fix 或 featurebreaking 优先security有安全影响的变更feature引入新功能的变更enhancement以用户可感知方式增强现有功能的变更fix修复 bug 的变更仓库中真实存在的示例包括 changelog.d/24410_aggregate_event_time_aggregation.feature.md、changelog.d/25723_grpc_decompression_error_detail.fix.md 等文件名直接体现了issue号_描述.类型.md的约定。6.3 内容编写要点内容必须是合法 Markdown且渲染为 changelog 列表中的单个列表项——因此避免使用标题语法分隔内容否则会成为主 changelog 中的标题改用换行分隔。一个好的 fragment 回答三个问题① 该变更如何影响用户可见行为② 影响哪些组件③ 引入或影响了哪些配置字段最后必须以authors:行结尾多个作者用空格分隔不要加前缀。breaking类型的 fragment 带有额外结构化字段H1 标题可含 Hugo 风格的{#anchor}锚点、## Summary和## Migration章节发布流程可据此自动生成升级指南纯告知型 breaking 的## Migration写N/A。推荐使用脚手架命令创建 fragment自动填写文件名、结构与作者行vdev changelog new fix 42_kafka_ack_race vdev changelog new enhancement retry_backoff_config vdev changelog new breaking env_var_interpolation并用vdev check changelog-fragments以与 CI 相同的方式校验校验文件名格式、authors:行以及 breaking fragment 的## Summary/## Migration结构。七、Release Highlights发布说明中的高价值变更由于 Vector 的发布往往包含大量变更项目使用 highlights 来突出高价值、有意义的变更。Highlights 是位于 website/content/en/highlights 目录下的 Markdown 文件精心描述一个特性每个 highlight 都会在相应的发布说明中显著展示。仓库中此类文件按YYYY-MM-DD-描述.md命名如2020-09-18-adaptive-concurrency等。7.1 FAQ什么值得写 Highlight什么样的 release highlight 才算值得写它应当为用户提供实际价值。这本质上是主观判断无法定义精确规则但要警惕产出低价值 highlight 而稀释其含义。通常一次发布不超过6 个highlights。7.2 FAQHighlight 与博客文章的区别Highlights 不是博客文章。它们是简短的一到两段式公告如果相关可以暗示或链接到更深入的博客文章。例如 adaptive concurrency自适应并发的公告本身值得写 highlight但这项带来性能和可靠性收益的工作同样值得一篇深入剖析的博客文章。八、文档工作流总览将以上流程串起来一个完整的文档维护闭环如下Rust 配置源码doc comments / schema 属性 │ make generate-component-docsvector generate-schema → JSON Schema → CUE ▼ website/cue/reference/components/{sources,sinks,transforms}/generated/name.cue │ 手工 CUE 文件标题、示例、how_it_works 等元数据 ▼ ./scripts/cue.sh fmt格式化 → CItrue make check-docs格式 vet 校验 │ ▼ website/content/en/docs/reference/configuration/{sources,sinks,transforms}/name.md网站页面 │ ▼ cd website make serve本地预览 → make check-generated-docsCI 一致性 │ ▼ changelog.d/name.type.md记录用户可见变更→ website/content/en/highlights/可选高价值特性这套体系的核心价值在于用 CUE 把源码文档与网站呈现连接起来——配置参数说明来自 Rust 注释、组件元数据由人工维护、生成结果经过 formatter 与 schema 双重校验从而保证官方文档始终与代码实现保持同步而 Changelog fragment 与 Release Highlights 则构成了面向用户的变更叙事层。相关资源docs/DOCUMENTING.md本文主体来源website/cueCUE 参考文档源码website/content/en/highlightsRelease Highlightschangelog.d/README.mdChangelog fragment 规范scripts/cue.sh 与 scripts/check-docs.shCUE 工具链src/generate_schema.rsgenerate-schema 命令实现website/cue/reference/components/transforms/remap.cue手工 CUE 文件示例【免费下载链接】vectorA high-performance observability data pipeline.项目地址: https://gitcode.com/GitHub_Trending/vect/vector创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考