Chat2DB 社区贡献指南：从 Issue 认领到代码合入的协作流程与工程实践

Chat2DB Community 是一款面向开发者、DBA、分析师与数据团队的免费、跨平台、本地优先的数据库客户端与 SQL 工作台，支持 40+ 数据库连接、SQL 编辑执行、数据管理与自带 AI 模型辅助生成/解释/优化查询。本指南以仓库根目录的 CONTRIBUTING.md 为骨架，结合 .github/ 下的贡献边界清单、社区运维合同、代码认领机器人源码与 CODEOWNERS 路由规则，完整讲解外部贡献者从「发现任务、认领任务、提交 Issue、提出 PR」到「通过评审、合入 main」的全流程，帮助你用最小摩擦把第一个贡献合入 Chat2DB。

一、开工之前：先了解项目与任务供给

1.1 如何找到可以做的事情

正式开始编码前，建议先浏览仓库的公开 Issue 与 Discussion：

• 新手优先选择小任务：小范围的 bug 修复、文档改进、Issue 复现（reproduction）、测试反馈是新手最容易上手并成功合入的贡献类型；
• 大改动先对齐方向：动手实现较大的变更前，请先开一个 Issue 或在已有 Issue 下留言，确认方向并避免与他人重复劳动；
• PR 与 Issue 关联：如果 PR 对应某个 Issue，请在 PR 描述中明确链接（例如 Closes #123）。

1.2 仓库的基本构成

从当前仓库结构看，Chat2DB Community 是一个典型的「前端 + 后端」双模块仓库：

• chat2db-community-client：TypeScript/React 前端客户端，包含 SQL 编辑器（SQLEditor）、AI 对话、数据库连接、结果集展示等模块；
• chat2db-community-server：Java 后端（Maven 多模块），其中 chat2db-community-plugins 下按数据库逐个拆分插件（MySQL、PostgreSQL、Oracle、Redis、MongoDB 等），chat2db-community-spi 定义插件与 SPI 契约；
• script/github：GitHub 协作自动化的 Node.js / Shell 脚本，如任务认领机器人、社区项目同步、标签同步等；
• .github：Issue 模板、CODEOWNERS、贡献边界清单、社区运维合同与 Actions 工作流。

二、社区队列接受什么：贡献边界地图

不是所有工作都能通过公开社区队列提交。仓库以 .github/contribution-boundaries.yml 作为唯一的贡献边界权威（contribution boundary map），为每个区域明确 status、boundary（允许的边界）与 alternative（替代路径）。

边界状态有三种：

状态	含义	示例区域
open	维护者可以直接划定范围并发布为任务	社区 bug 修复、文档/测试/示例/翻译
approval-required	开工前必须先记录设计或所有权决策	新数据库插件、公共契约/存储格式、新 AI Provider、发布与打包
closed	不接受公开实现，只解释原因并提供替代路径	敏感安全细节、商业版本、无边界的大规模重写

2.1 最容易通过的贡献类型

• 社区 bug 修复：针对可复现行为的有界修复（community-bug-fixes，状态 open）；
• 文档、测试、示例与翻译：面向公开社区行为的文档、测试、示例与翻译（docs-tests-and-examples，状态 open）。

2.2 需要维护者批准的区域

• 数据库插件：新数据库插件及对插件契约的实质性修改，需要先有被接受的设计与长期维护者（database-plugins，approval-required）；替代路径是向现有插件贡献有界的兼容性修复或测试；
• 公共契约与存储：公共 API、持久化工作区数据、迁移格式与跨客户端契约，实现前需要设计批准（public-contracts-and-storage）；
• AI Provider 集成：新 AI Provider 及 Provider 专属协议分支，需要证明公共兼容层无法支持该 Provider（ai-provider-integration）；
• 发布与打包：安装器依赖、签名、更新通道、制品发布与发布工作流，需要 Release Owner 批准（release-and-packaging）。

2.3 不接受公开队列的区域

• 敏感安全：漏洞细节、利用代码、凭据与私有修复不通过公开 Issue 接收，应走 SECURITY.md 中的私有上报渠道（sensitive-security，closed）；
• 商业版本：Chat2DB Local、Pro、Enterprise、Gateway、许可、计费与私有服务实现都不属于社区贡献队列（commercial-editions，closed）；
• 无边界重写：没有已接受 Issue 支撑的全仓重写或投机性架构替换不算 contributor-ready 工作（unbounded-rewrites，closed）。

从源码看，这份清单还带维护元数据：owner: openai0229、reviewed_on、review_after: "2026-10-31"，意味着边界规则会按周期复审，贡献者提交前可先查看该文件的当前状态。

三、发现并认领任务：Ready Contract 与 /claim 机制

3.1 公开工作视图

公开的 Chat2DB Community Project 呈现 triage、contributor-ready、active、review、release 五个阶段的卡片流。Issue 是唯一事实源（source of truth），Project 只是共享工作流视图。对外部贡献开放的任务会打上以下两种标签之一：

• contribution/good-first-issue：有界工作，适合首次贡献；
• contribution/help-wanted：有明确范围、维护者欢迎贡献的工作。

3.2 Maintainer Ready Contract

一个已发布的任务，其 Issue 正文会附带完整的 Maintainer Ready Contract，至少包含：用户结果（user outcome）、范围（in scope）、非目标（non-goals）、建议的代码/文档区域、验收标准（acceptance criteria）、精确验证方式（exact verification）、依赖或所需环境、评审维护者（review maintainer）、首次实质评审目标（默认 5 个工作日）、里程碑（版本号或 Not release-committed）。

注意：不要因为某个 Issue 出现在 Milestone 里就直接开工。Milestone 只表达交付窗口；任务货架（task shelf）是 Project 的 Available Tasks 与 Good First Issues 视图。

3.3 认领命令与七天租期

对可认领的任务，在 Issue 下评论 /claim 即可发起认领。认领成功后：

• Issue 会分配给你；
• 你有 7 天时间打开一个关联的 draft 或正式 PR；
• 每个贡献者同一时间只能持有一个活跃认领（对应认领策略配置中的 maxActiveClaimsPerUser 必须为 1）。

认领机器人还支持以下命令：

命令	作用
/claim	认领一个可用任务
/claim status	显示认领人、截止时间与关联 PR
/renew	对 PR 前阶段的活跃认领延长一次（最多一次）
/unclaim	立即释放当前认领

PR 一旦关联，只要维护者还欠着评审，PR 前的截止时间就不再继续流逝。请务必在 PR 描述中使用 Closes #123，让 Issue、PR 与 Project 保持联通。认领后逾期未打开关联 PR 的，认领会自动释放给下一位贡献者继续处理。

3.4 认领机器人的源码实现

仓库中 script/github/issue-claim.js 完整实现了这套逻辑，可以作为理解机制的底层依据：

• 命令解析（parseCommand）：将 Issue 评论体小写化后精确匹配 /claim、/unclaim、/renew、/claim status；
• 策略校验（loadPolicy）：要求策略版本为 1、eligibleLabels 非空、leaseDays 为正整数、maxActiveClaimsPerUser 为 1，否则直接抛错拒绝加载；
• 资格判定（isEligibleIssue）：只有 open 状态、非 PR、且带 eligibleLabels 中标签的 Issue 才可认领；
• 状态机（VALID_STATUSES）：认领状态分为 unclaimed、active、released、expired，认领状态以 <!-- chat2db-claim-state:{...} --> 标记持久化在 Issue 正文中。

配套的 issue-claim.test.js 与 .github/workflows/issue-claim.yml 工作流负责调度与验证，认领命令的响应全部由 GitHub Actions bot 完成。

3.5 维护者的响应承诺

社区运维合同（.github/COMMUNITY_OPERATIONS.md）为维护者设定了明确的响应目标：

事件	目标
Ready Issue 上的提问	3 个工作日
首次实质性 PR 评审	5 个工作日
贡献者修改后的跟进评审	3 个工作日

若无法按期完成，负责的维护者必须公开说明阻塞原因与下次评审日期。注意：自动化确认（bot 回复）不算实质性响应。

四、提交高质量 Issue：Bug 报告与功能请求

4.1 Bug 报告模板要点

提交 bug 前请先搜索已有 Issue，避免重复报告。一个可复现、可理解的 bug 报告应包含：

• 清晰且描述性的标题；
• Chat2DB 版本；
• 使用方式：桌面应用 / Docker / 本地源码构建；
• 操作系统；
• 数据库类型与版本；
• 复现步骤；
• 期望行为与实际行为；
• 可行的日志、截图或录屏。

对数据库连接或 SQL 执行类问题，额外建议附上：所用数据库、连接方式（不要包含密码或隐私信息）、一段安全的最小 SQL 示例。

⚠️ 安全提醒：粘贴日志或截图前，务必移除密码、令牌、私有主机名、客户数据等敏感信息。

仓库在 .github/ISSUE_TEMPLATE 中为不同类型准备了表单，其中 database_bug.yml 专门收集数据库类缺陷的字段，与上述清单对应。

4.2 功能请求要点

功能请求同样先搜索已有 Issue 与 Discussion。带有清晰用例的请求更容易讨论，建议包含：清晰描述性标题、希望改进的问题或工作流、期望的功能、示例用例、有用的截图/Mockup/参考资料。

4.3 Discussions 与 Issues 的分工

仓库明确划分了两类渠道的用途：

• GitHub Discussions：使用问题、安装/环境搭建求助、想法与开放式反馈、社区支持、一般产品讨论；
• GitHub Issues：可复现的 bug、明确的功能请求、文档问题、可以动手执行的技术任务。

这套分工让 Issue 保持聚焦、更易管理，也便于认领机器人与项目板自动流转。

五、提交 Pull Request：流程、描述与链接规范

5.1 提交前的八步清单

1. Fork 仓库；
2. 创建或评论相关 Issue；若任务已发布为可认领任务，先认领再开工；
3. 为你的工作创建新分支；
4. 保持 PR 聚焦于单一主题；
5. 如果变更影响用户行为或安装配置，同步更新文档；
6. 尽可能补充或更新测试；
7. 本地完整验证变更；
8. 在 PR 描述中链接相关 Issue。

Issue 关联写法（二选一）：

Fixes #123

或：

Related to #123

5.2 良好的 PR 描述应包含

• 改了什么（What changed）；
• 为什么需要（Why the change is needed）；
• 关联 Issue 链接；
• 如何测试的（How you tested it）；
• UI 变更附截图或录屏；
• 已知限制或后续工作。

请避免在一个 PR 中混入无关改动——小 PR 更容易被评审和合入。

六、Trusted Contributors：评审路由与角色边界

6.1 角色定义与成员

Trusted Contributors（信任贡献者） 是由仓库管理员邀请的资深社区贡献者，通过 @OtterMind/chat2db-community-contributors 团队授予，权限仅限本仓库，不是 Maintainer 或 Release Owner。当前信任贡献者及其专注领域：

评审人	主要专注领域
@auenger	AI UI、模型配置、聊天流、提示词、知识管理、社区 AI 后端行为
@Aias00	数据库连接、插件与 SPI、元数据与对象管理、SQL 执行、SQL 编辑、结果处理
@openai0229	任何区域，尤其是跨切面变更、仓库治理、安全、打包与发布

专注领域是路由指引而非排他所有权：任何 Issue/PR 都可以请求 @openai0229 评审。

6.2 CODEOWNERS 路由规则

.github/CODEOWNERS 将这些领域映射到具体路径，PR 作者应按映射直接请求对应评审人：

• AI 相关路径（如 src/blocks/AI、src/store/ai、src/service/ai*.ts、AiChatController.java、AiToolMcpAdapter.java 等）应直接请求 @auenger，其批准可满足 Code Owner 要求；当 @auenger 本人是作者或最新推送者时，@openai0229 作为后备 Code Owner；
• 数据库相关路径（如 src/blocks/CreateConnection、src/components/SQLEditor、service/connection.ts、chat2db-community-plugins、chat2db-community-spi、Db*.java 控制器等）应直接请求 @Aias00，其批准可满足 Code Owner 要求；@openai0229 是后备 Code Owner；
• /.github/、/script/github/、/script/package/、/docker/ 下的变更必须由 @openai0229 作为 Code Owner 批准，Trusted Contributor 的评审欢迎但不能替代该批准。

6.3 合入 main 的完整门槛

当 PR 目标为 main 时，仓库规则要求全部满足：一个批准评审、Code Owner 批准、最新推送后由非最新推送者的他人批准、全部必需状态检查通过、所有评审对话已解决。Trusted Contributor 只有等 GitHub 报告这些条件全部通过后才能评审并合入；批准人必须既不是作者也不是最新推送者。

6.4 角色权限与禁止事项

Trusted Contributor 可以：

• 创建与更新非受保护分支；
• 评审社区 PR，帮助贡献者解决评审线程；
• 在所有必需条件通过后合入 main；
• 手动从 main 运行 Build Community Desktop Release 工作流，传入不带 v 前缀的数字版本（如 5.3.4），在 GitHub Actions 中产出 beta 制品。

Trusted Contributor 不可以：

• 直接 push 或 force-push 到 main；
• 绕过必需评审、状态检查、Code Owner 批准、最新推送批准或未解决的评审对话；
• 创建、更新或删除 release 标签；
• 发布正式 GitHub Release 或社区 Docker 镜像；
• 修改仓库访问权限、rulesets、环境或 Actions 密钥；
• 把 beta 工作流访问权当作签名凭据——密钥值永远保密，不得打印、复制或泄露。

Beta 运行只发布 GitHub Actions 制品；正式发布与 Docker 发布必须从受保护标签开始，且始终由 Release Owner 负责。

6.5 角色授予与撤销

管理员基于以下因素授予/撤销该角色：持续有效的贡献、评审质量、安全意识、对社区工作流的熟悉程度，以及项目当前对额外评审人的需求。

七、从认领到合入的端到端状态流

结合 .github/COMMUNITY_OPERATIONS.md 中定义的 Project 状态矩阵，一个贡献的完整生命周期如下：

证据	Project 状态
新 Issue 等待 triage	Inbox
已确认但不可执行	Backlog
Ready Contract 完备、无关联 PR	Ready
已关联 draft 或正式 PR	In Progress
PR 就绪等待维护者评审	In Review
Issue 关闭或 PR 合并	Done

维护者每周都会核对 Project：清理 Done 外的已关闭项、Done 中的未关闭项、没有 contribution/* 标签的 Ready 项、没有评审负责人的已发布任务、过期 Milestone。仓库中的 .github/workflows/community-project-sync.yml 与 script/github/sync-community-project.js 负责把 Issue/PR 状态同步到 Project 板，sync-community-project.test.js 为其提供测试保障。

八、本地搭建、求助与贡献者认可

8.1 本地搭建

请以 README.md 中的最新安装说明为准。若搭建遇到问题，向社区求助时请附上：执行的命令、错误输出、你的本地环境详情（操作系统、Java/Node 版本等）。

8.2 遇到困难去哪里求助

• 相关 GitHub Issue 下留言；
• GitHub Discussions；
• README 中列出的 Chat2DB 社区渠道。

8.3 贡献者认可与授权

项目感谢每一种形式的帮助，包括代码、文档、测试、bug 报告、Issue 复现、PR 评审与社区支持。

关于授权，请注意 CONTRIBUTING.md 与 LICENSE 的条款：向 Chat2DB 贡献即表示你同意你的贡献按项目当前 LICENSE 授权，同时同意 Chat2DB 可将你的贡献用于商业目的，并可能纳入未来以不同许可条款发布的版本中。提交贡献前请先阅读 LICENSE。

结语

Chat2DB Community 的协作体系把「任务发布 → 认领 → 实现 → 评审 → 合入 → 发布」全程显式化：贡献边界地图划定可做与不可做，Ready Contract 把范围与验收标准写进 Issue，认领机器人用 /claim 与七天租期管理并发，CODEOWNERS 把 AI 与数据库两大技术域路由给对应专家，SLA 目标则约束了评审节奏。对于外部贡献者，最佳起点始终是：找一个带 contribution/good-first-issue 或 contribution/help-wanted 标签的小任务，在 Issue 下评论 /claim，然后提交一个聚焦、带测试、链接了 Issue 的小 PR——这正是本仓库最欢迎、也最容易合入的贡献形态。