GreptimeDB 贡献指南：从首个 Issue 到合入 PR 的完整开发协作流程-平芜编程栈

GreptimeDB 贡献指南：从首个 Issue 到合入 PR 的完整开发协作流程

【免费下载链接】greptimedbThe open-source observability database. One columnar engine for metrics, logs, and traces, on object storage.项目地址: https://gitcode.com/GitHub_Trending/gr/greptimedb

导读：本文以 GreptimeDB 官方贡献文档（CONTRIBUTING.md）为主体，结合仓库内 Makefile、docs/style-guide.md、licenserc.toml 等真实文件，完整梳理向这个开源可观测性数据库提交代码的全流程——包括 Issue 提交流程、PR 提交前的质量门禁（license 头、格式化、单元测试、clippy、无用依赖检查）、pre-commit 钩子配置、Conventional Commits 提交规范，以及仓库对 AI 辅助贡献的明确政策。读完本文，你将掌握一套可直接落地的、被项目维护者认可的贡献工作流。

社区与协作基础

GreptimeDB 是一个基于 Apache 2.0 许可的开源可观测性数据库，采用单一列式存储引擎统一承载 metrics、logs、traces，并构建在对象存储之上。项目欢迎任何人以代码、文档、布道等形式参与共建，并强调开放对话、相互尊重与过程透明。

仓库内定义了两级社区角色：

Contributor（贡献者）：任何提交高质量贡献（代码、文档、推广等）的社区成员。
Committer（提交者）：持续数月保持高质量贡献的贡献者，将获得 GreptimeDB 仓库的读写权限。当前全部个人 Committer 名单维护在 AUTHOR.md 中（按字母序列出个人 Committer 与团队成员），你可以在此核对项目认可的核心维护者。

社区沟通的基本原则是：与维护者交流时保持礼貌与尊重；维护者也会以同样态度回应你的 Issue、审阅你的变更并协助合入 PR。

第一次贡献：从小处开始

初次接触大型 Rust 代码库时容易感到不知所措，CONTRIBUTING.md 给出的建议非常务实：

遵守仓库的 Code of Conduct；
小改动也能带来大价值——哪怕是一个单字符的修正 PR，只要对项目有益都会被欣然接受，不必等到万事俱备才动手；
提交新 Issue 前，先检索并查看已关闭的 Issue，避免重复报告；
尽量遵循代码库现有的风格；
有疑问时大胆提问。

这里需要说明：Code of Conduct 等社区公约的外部链接可在 GitHub 组织仓库中找到；在本地仓库中，与贡献规范直接相关的文件是 CONTRIBUTING.md 本身与 AUTHOR.md。

除了代码 PR，项目同样欢迎以下形式的贡献：

撰写教程或博客：围绕 GreptimeDB 的某个特性输出技术文章，项目方会给予素材支持并在官方渠道推广；
改进文档：文档更新、增强、设计说明、缺陷修复乃至拼写语法修正都受欢迎；
在 meetup 与会议上分享：基于 GreptimeDB 的真实使用场景与挑战做演讲；
提交 bug 报告：通过 GitHub Issue 报告 bug 或安全问题；
提出 feature request：通过 GitHub Discussions 发起讨论，或通过 Slack 等渠道与团队沟通使用场景与想法。

提交 Issue 的正确姿势

提交高质量的 Issue 是高效协作的第一步，流程如下：

先搜索再提交：使用搜索栏确认该问题是否已被覆盖；
选择合适的模板：GitHub 提供的 Issue 模板中，选择最适合当前场景的那一个（bug、安全、功能等）；
提交后保持跟进：维护者会尽快对 Issue 进行分类和指派；请耐心等待，并尽可能提供充分信息以帮助定位问题或达成共识。

遇到任何阻碍时，可通过 Slack 等社区渠道向更广泛的受众求助。

PR 之前的准备清单

这是整个贡献流程中最具操作性的部分。CONTRIBUTING.md 明确列出了提交 PR 前必须满足的硬性检查项，下面逐条结合仓库文件说明其底层实现。

1. 签署 Contributor License Agreement（CLA）

为确保社区对贡献内容的使用权没有疑虑，提交 PR 前需要签署 CLA，该流程会嵌入在 PR 提交过程中（由 CI 机器人检查）。

2. 确保所有文件带有正确的 license header

仓库通过 hawkeye 工具统一检查/格式化版权头，在项目根目录执行：

docker run --rm -v $(pwd):/github/workspace ghcr.io/korandoru/hawkeye-native:v3 format

license 头检查的配置在 licenserc.toml：覆盖*.rs、*.py、*.ts三类文件，版权年从 2023 年开始，版权方为 "Greptime Team"。值得注意的是，该文件通过# enterprise:start/# enterprise:end标记区划出一批不适用 Apache-2.0 头的文件（如src/sql/src/statements/alter/trigger.rs、src/mito2/src/extension.rs等），这些文件受 GreptimeDB Enterprise License 约束，并单独由 licenserc-enterprise.toml 管理。

两块 license 配置的一致性由 scripts/check-enterprise-license.py 脚本（对应make check-enterprise-license）自动校验：凡是被#[cfg(feature = "enterprise")]门控的模块文件，必须同时出现在 enterprise 配置的includes与 Apache 配置的excludes中，防止企业功能文件错误地带上 Apache-2.0 头。因此，如果你新增了企业特性门控下的文件，务必同步更新两份 license 配置。

3. 遵循代码风格与格式

所有代码必须格式化，并遵循项目编码风格。项目风格要求包含两方面：

通用 Rust 风格规范；
仓库专属的 docs/style-guide.md，其中明确了：
- 格式化：所有mod声明放在use之前；对"不太可能实现的功能"使用unimplemented!()而非todo!()；声明块前后留空行；注释放在#[attribute]/#[derive]之前；
- 模块组织：使用与模块同名的文件（如cache.rs+cache/目录）而非mod.rs；
- 注释：公共函数与结构体必须加注释，优先使用文档注释///；
- 错误处理：按需定义模块级自定义错误类型；优先使用context()（参数会被立即求值），仅在错误路径上才有开销的上下文构造使用with_context()，例如：

value.with_context(|| InvalidValueSnafu { reason: format!("invalid value: {value}"), })?;

日志统一通过common_telemetrycrate 的error!()/warn!()宏输出，例如error!(e; "Failed to do something");。

仓库为格式化提供了自动化入口：make fmt（cargo fmt --all）与make fmt-check。其中fmt-check除了cargo fmt --all -- --check之外，还会运行两个仓库自研的 Python 检查脚本：

scripts/check-snafu.py：扫描所有error.rs中定义的#[snafu(display(...))]错误变体，确保每个XxxSnafu变体都在代码中真正被使用，防止出现"定义了却没人用"的死错误变体；
scripts/check-super-imports.py：检查所有 Rust 文件中是否存在行首无缩进的use super::导入（这类导入必须带一个前置 tab 缩进）。

4. 通过全部单元测试

使用 nextest 运行全部单元测试（注意此为项目官方推荐的测试运行器）：

cargo nextest run --workspace --features pg_kvbackend,mysql_kvbackend

或使用等价的 Make 目标：

make test

仓库的 Makefile 中，test目标实际执行的是cargo nextest run ${NEXTEST_OPTS}，其中NEXTEST_OPTS默认携带--retries 3 --features pg_kvbackend,mysql_kvbackend，并会根据机器核数自动设置--build-jobs（核数减半，少于 2 核时取 1），兼顾了稳定性与构建速度。此外make test会自动检查cargo-nextest是否已安装（cargo --list | grep nextest），未安装时通过cargo install cargo-nextest --locked安装。

如果你需要运行 SQL 集成测试（sqlness），可执行make sqlness-test；模糊测试用make fuzz（默认 target 为fuzz_alter_table，可通过FUZZ_TARGET覆盖，fuzz 工程位于 tests-fuzz）。分布式/集成测试样例位于 tests 目录（含 standalone 与 distributed 两类 case）。

5. 修复所有 clippy 告警

cargo clippy --workspace --all-targets -- -D warnings

或：

make clippy

Makefile 中的clippy目标为cargo clippy --workspace --all-targets --all-features -- -D warnings（注意比文档命令多了--all-features），另有make fix-clippy可自动修复违规。CI 将-D warnings视为硬性门禁，任何 warning 都会导致失败。

6. 清理无用依赖

运行：

make check-udeps

该命令基于 cargo-udeps（cargo udeps --workspace --all-targets）找出未被使用的依赖；若报告出问题，用make fix-udeps自动清理——它会先以 JSON 格式导出 udeps 报告，再由 scripts/fix-udeps.py 脚本解析并删除无用依赖。

如果某个依赖是有意保留的目标特定依赖（例如放在[target.'cfg(...)'.dev-dependencies]下），需要在对应的Cargo.toml中添加 cargo-udeps 的 ignore 条目，例如：

[package.metadata.cargo-udeps.ignore] development = ["rexpect"]

（dependencies/build视实际位置相应调整。）

7. 修改示例配置后更新配置文档

当修改 config 目录下的示例配置文件（如datanode.example.toml、standalone.example.toml、metasrv.example.toml、frontend.example.toml、flownode.example.toml）时，需要运行：

make config-docs

该目标在 Makefile 中通过toml2docs/toml2docs:v0.1.3容器镜像生成文档：以 config/config-docs-template.md 为模板（小节标题前缀##），输出到 config/config.md。生成的配置文档变更需要一并包含在你的提交中（该命令依赖本机 Docker）。

配置 pre-commit 钩子

为了把上述检查固化到日常开发中，可以在每个 commit 时自动执行这些检查。pre-commit 的安装步骤在 CONTRIBUTING.md 中有完整说明：

第一步：安装 pre-commit

pip install pre-commit

或（macOS）：

brew install pre-commit

第二步：安装项目钩子

$ pre-commit install pre-commit installed at .git/hooks/pre-commit $ pre-commit install --hook-type commit-msg pre-commit installed at .git/hooks/commit-msg $ pre-commit install --hook-type pre-push pre-commit installed at .git/hooks/pre-push

此后每次git commit时 pre-commit 会自动运行。它同时覆盖 commit-msg 与 pre-push 两个阶段：前者校验提交信息是否符合规范，后者在推送前执行代码检查，把"到 CI 才发现问题"的循环提前到本地。

PR 的标题、描述与提交信息规范

GreptimeDB 采用 Conventional Commits 规范（此为项目文档引用的提交信息规范，其语法如下述示例所示）：

PR 标题

PR 标题必须以类别名作为前缀，例如feat/fix/docs，后接对该变更的简洁概括，格式如：

feat: support querying vector columns via pg protocol fix: correct the timezone handling in promql instant queries docs: refine the standalone deployment guide

注意：不要直接复用最后一次 commit 的 message 作为 PR 标题。

PR 描述

小型 PR（如拼写修正）可以写得很简短；
包含较大代码变更的 PR，务必说明动机与设计细节，让 reviewer 能理解你的意图；
若 PR 包含 breaking change 或 API 变更，必须在描述中明确列出。

Commit Message

所有 commit message 都应遵循 Conventional Commits 规范。仓库的 changelog 生成工具配置（cliff.toml）正是依赖这一规范：它开启conventional_commits = true，并按feat、fix、doc(s)、perf、refactor、style、test、chore/ci、revert等前缀把提交自动归类到 changelog 的不同分组。也就是说，规范的提交信息不仅是协作礼仪，还直接决定发布时 changelog 的质量。

AI 辅助贡献政策

随着 AI 编码工具的普及，CONTRIBUTING.md 对 AI 生成的 PR 给出了明确的立场，这是当前仓库一项极具现实意义的政策：

对 AI 辅助 PR 的要求：

PR 作者必须端到端理解实现背后的核心思想，并能在 review 过程中为设计与代码辩护；
主动指出未知与假设：对 AI 生成代码中自己不完全理解的部分，应在评论中明确指出（例如："这个函数在这里调用看起来能用，但我对其内部实现不熟悉，怀疑并发调用时是否存在竞态条件"），让 reviewer 借助代码库知识来澄清疑虑。

为什么"完全 AI 生成且不理解"的 PR 没有价值：代码评审的两大目的是——(1) 完成任务本身；(2) 在作者与 reviewer 之间分享知识，这是对项目的长期投资。一份"AI dump"式 PR 两者都达不到：维护者自己用 AI 可能更快，而提交者若只是充当 AI 的传声筒，也无法从中获得成长。由于项目的 review 容量非常有限，看起来缺乏必要理解的大型 PR 可能得不到评审，并最终被关闭或重定向。

比"AI dump"更好的贡献方式：撰写一份高质量 Issue——包含清晰的问题陈述与最小可复现示例，这会让他人更容易接手贡献。

遇到困难时如何求助

卡住时的推荐路径：

提交 Issue：描述你尝试做什么、发生了什么错误，附上详细细节；
Slack 频道：在 GreptimeDB 社区 Slack 中提问，触达更广的开发者群体。

社区参与入口（按 CONTRIBUTING.md 所列）：GreptimeDB 社区 Slack、GitHub Discussions，以及官方文档站与产品页。想快速理解项目全貌，可以从仓库根目录的 README.md 与 docs 目录入手——后者包含架构图、设计 RFC（docs/rfcs 下的系列提案）与部署/使用指南。

小结：一次贡献的完整路径

在 GitHub Issues 中搜索/提交 Issue，与维护者对齐问题；
克隆仓库，创建分支，做出最小可用的改动；
签名 CLA，运行 hawkeye 补齐 license header；
按 docs/style-guide.md 与 rustfmt 规范格式化，运行make fmt-check（含 snafu 与 super-imports 专项检查）；
通过make test（nextest）、make clippy、make check-udeps；
若改了 config 示例配置，运行make config-docs并提交生成的 config/config.md；
本地配置 pre-commit 钩子，让检查自动执行；
使用 Conventional Commits 规范书写 commit 与 PR 标题/描述，明确列出 breaking change；
耐心等待 review，积极回应反馈——若使用 AI 辅助生成代码，务必理解核心逻辑并在不确定处主动标注。