贡献指南

欢迎大家踊跃投稿，我们将不胜感激！点滴之助，必有回报。

目录

• 贡献

  • 目录

  • 贡献类型

    • 报告错误

    • 提交想法或功能请求

    • 修复错误

    • 实施功能

    • 改进文档

    • 提问

  • 拉取请求指南

    • 规程

      • 编写

      • 检查

      • 合并

      • 合并后的任务

  • 管理问题和 PR

  • 设置本地开发环境

贡献类型

报告错误

报告错误的最佳方式是在 GitHub 上提交问题。请包括：

• 您的操作系统名称和版本。

• Dingo 数据库版本。

• 重现错误的详细步骤。

• 有关您本地设置的任何详细信息，这些信息可能有助于故障排除。

提交想法或功能请求

最好的方法是在 GitHub 上提交问题：

• 请详细解释如何操作。

• 尽可能缩小范围，以便于实施。

• 请记住，这是一个由参与者推动的项目，欢迎大家踊跃投稿：)

对于大型功能或代码库的重大变更，请创建 DingoDB 改进提案 (DIP)。请参见 DIP-0 中的模板。

修复错误

查看 GitHub 上的问题。标有 #bug 的问题对任何想实现它们的人开放。

实施功能

查看 GitHub 上的问题。标有 #feature 的问题对任何想实现它的人开放。

改进文档

DingoDB 需要更好的文档，无论是作为官方文档的一部分，还是作为博文或文章在网络上发布。

提问

在 Mailing list 上有专人负责解答您的问题。

拉取请求指南

我们要大力提倡的理念是

在创建 PR 之前，先创建一个问题。

目的是将问题与可能的解决方案区分开来。

错误修复： 如果您只是修复一个小错误，立即提交拉取请求即可，但我们强烈建议您提交一个问题，详细说明您要修复的问题。如果我们不接受该特定修复，但又想跟踪该问题，这将很有帮助。请记住，项目维护者有权接受或拒绝收到的 PR，因此最好将问题和修复代码分开。在某些情况下，项目维护者可能会要求您在继续之前创建一个独立于 PR 的问题。

重构： 对于小规模的重构，可以是一个独立的 PR，详细说明重构的内容和原因。如果有疑虑，项目维护者可能会要求你在继续之前为 PR 创建一个 #DIP。

功能/大改动： 如果您打算更改公共 API，或者对实现进行任何非小规模的改动，我们要求您提交一个新的问题作为 #DIP (DingoDB Improvement Proposal)。这可以让我们在您投入大量精力之前就您的提议达成一致。我们也欢迎您在提交 DIP 的同时提交 PR（有时是演示所必需的），但在 DIP 被批准之前，我们不会审核/合并代码。

一般来说，小型公关总是比大型公关更容易审核。最好的做法是将您的工作分成较小的独立公关，并提及同一问题。这将大大缩短周转时间。

如果您想分享尚未准备好合并的工作，请创建一个 Draft PR。这将有助于维护者和 CI 运行人员优先处理成熟的 PR。

最后，千万不要提交会使主分支处于崩溃状态的 PR。如果 PR 是为完成一个大型功能而提交的多个 PR 的一部分，且无法独立运行，那么可以创建一个功能分支，将所有相关的 PR 合并到功能分支中，然后再创建从功能分支到主分支的 PR。

规程

编写

• 填写 PR 模板的所有部分。

• 用以下语义前缀之一为 PR 命题（受 Karma启发）：

  • feat（新功能）

  • fix (错误修复)

  • 文档（对文档的修改）

  • style（格式化、缺少分号等；不改变应用程序逻辑）

  • refactor (重构代码)

  • test （添加缺失的测试、重构测试；不改变应用程序逻辑）

  • chore （更新任务等；不改变应用程序逻辑）

  • perf （与绩效有关的变化）

  • build （构建工具、Docker 配置更改）

  • ci （测试运行器、Github 操作工作流程变更）

  • other（与上述内容不一致的更改 -- 应该很少见！）。

  • 示例：

    • 特征：将图表导出为 ZIP 文件

    • perf(api): 提高应用程序接口信息的性能

    • 修正(chart-api)：缓存指示器始终显示已缓存的值

• 如果尚未准备好接受审核，请在标题中添加前缀 [WIP]（WIP = 进行中的工作）。我们建议先创建 PR，并在通过 CI 测试并至少通读一次代码更改后删除前缀[WIP]。

• 如果您认为您的 PR 有可能带来破坏性改动，请在语义前缀之后、PR 标题的冒号之前加上 ！，就像这样： feat！：为 bar 添加 foo 功能

• 屏幕截图/GIF： 更改用户界面需要截图前/后，或 GIF 进行交互

  • 推荐的捕捉工具（Kap、LICEcap、Skitch）

  • 如果没有提供截图，提交者会在 PR 上标注 need:screenshot（需要截图）标签，在提供截图之前不会进行审核。

• 依赖关系： 添加新的依赖关系时要小心谨慎，避免不必要的依赖关系。

• 测试： 拉取请求应包括测试，可以是 doctests、单元测试，或两者兼而有之。确保解决所有错误和测试失败。

• 文档： 如果拉取请求增加了功能，文档应作为同一 PR 的一部分进行更新。

• CI： 审核人员在所有 CI 测试通过之前不会审核代码。有时，测试可能会出现问题。您可以关闭并打开 PR 以重新运行 CI 测试。如果问题仍然存在，请报告。在 CI 修复被部署到 “master ”后，请重置您的 PR。

• 代码覆盖率： 请确保代码覆盖率不降低。

• 准备就绪后，删除 [WIP]。请注意，批准后可能很快就会合并，因此请确保 PR 已准备好合并，且不要期望有更多时间进行批准后的编辑。

• 如果 PR 尚未准备好接受审核，且静止时间超过 30 天，我们将以静止为由关闭 PR。欢迎作者重新打开并更新。

检查

• 在撰写评论时使用建设性的语气。

• 如果需要修改，应明确说明在批准 PR 之前需要做哪些工作。

• 如果您被要求更新您的拉取请求，并做出一些修改，您无需创建一个新的拉取请求。将您的更改推送到同一分支即可。

• 提交者保留拒绝任何 PR 的权利，在某些情况下可能会要求作者提交问题。

合并

• 合并 PR 至少需要一个批准。

• 在合并前，PR 通常至少要开放 24 小时。

• 合并 PR 后，关闭相应的问题。

合并后的任务

• 如果 PR 引发了新问题，项目维护者可以联系 PR 作者。

• 如果发现关键问题，如破坏主分支 CI，项目维护人员可能会还原你的更改。

管理问题和 PR

为了处理收到的问题和 PR，提交者会阅读问题/PR，并用标签对其进行标记，以进行分类并帮助贡献者发现应采取的行动，因为贡献者通常具有不同的专业知识。

分流目标

• 针对问题： 对问题进行分类、筛选，标记作者需要采取的行动。

• 对于 PR： 进行分类，标记作者需要采取的行动。如果 PR 已准备好接受审核，则标记审核人员的必要操作。

首先，添加类别标签（又称哈希标签）。每个问题/PR 必须有一个哈希标签（垃圾邮件条目除外）。以 # 开头的标签定义了问题/PR 类型：

标签	供发布	供提交 PR
#bug	错误报告	错误修复
#code-quality	描述代码、架构或效率方面的问题	重构、测试、工具
#feature	新功能请求	新功能的实施
#refine	提出不提供新功能，也不是错误修复或重构的改进建议，如调整 padding、改进 UI 风格。	实施不提供新功能的改进，也不是错误修复或重构，如调整填充、改进用户界面风格。
#doc	文档	文档
#question	故障排除： 安装、本地运行、询问如何操作。稍后可改为 #bug。	N/A
#DIP	DingoDB 改进建议	N/A

然后酌情添加其他类型的标签。

• 需求标签： 这些标签的模式为 need:xxx，描述了进展所需的工作，如 need:rebase、need:update、need:screenshot。

• 风险标签： 这些标签的模式为 “risk:xxx”，描述了采用该工作的潜在风险，如 “risk:db-migration”。这样做的目的是为了更好地了解影响，并为需要更严格测试的 PR 创建意识。

• 状态标签： 这些标签描述了状态（“放弃”、“不想修复”、“可以重新生成 ”等）。被拒绝或未完成就关闭的问题/PR 应具有一个或多个状态标签。

• 版本标签： 这些标签的模式为 vx.x，如 v0.28。问题上的版本标签描述了错误报告的版本。PR 上的版本标签描述的是包含 PR 的第一个版本。

如果作者提供的标题描述性不够，提交者也可以更新标题以反映问题/PR 的内容。

如果 PR 通过了 CI 测试，且没有任何 “need: ”标签，则可以进行审核，添加标签 “review ”和/或 “design-review”。

如果某个问题/PR 在 >=30 天内一直处于非活动状态，则会被关闭。如果没有任何状态标签，则添加 “未激活”。

设置本地开发环境

首先，fork GitHub 上的仓库，然后克隆它。你可以直接克隆主仓库，但不能发送拉取请求。

git clone git@github.com:your-username/dingo.git
cd dingo
./gradlew build