贡献代码
Contents
本页包含有关贡献代码的一般指南和程序。如果您有任何问题，请在maria-developers邮件列表、我们在 https://mariadb.zulipchat.com 的 Zulip 实例或 #maria IRC 频道（在https://libera.chat/上）上提问。其他查找 MariaDB 的电子邮件列表和位置可以在这里找到。
有关向 MariaDB 贡献的一般信息（供开发人员和非开发人员使用）可在Contributing to the MariaDB Project页面找到。
寻找要开发的项目
MariaDB 有许多您可以为其做出贡献的开放式开发项目（除了您自己的任何想法）。
- 我们正在使用JIRA管理 MariaDB 项目。转到https://jira.mariadb.org并单击“项目”即可进入 MariaDB 项目。浏览未解决的、未分配的问题，看看是否有您感兴趣的内容。有些问题有赞助商，您可以得到报酬！
- 我们还提供了适合初学者的任务列表。
- 检查下一个 MariaDB 版本的开发计划。
- 加入maria-developers 并写信给 maria-developers@lists.launchpad.net 列表，询问您可以完成的任务建议。请在电子邮件中包含您的编程经验、您对 MariaDB 源码的了解以及您对使用 MySQL/MariaDB 的了解程度，以便我们知道可以向您建议哪些任务。
- 如果这是您的第一个项目，请查看建议的开发页面。它列出了一个很好的开端项目。
- 加入 MariaDB 的 Zulip 实例，网址为 https://mariadb.zulipchat.com，并寻求建议。
- 加入https://libera.chat/ IRC上的 #/maria，并寻求建议。
如果您有自己的想法，请将它们提交到JIRA，以便其他 MariaDB 开发人员可以对其进行评论并建议如何实现它们。当然，您也可以使用maria-developers 列表。
对MariaDB Server开发者的期望
本节主要是针对具有对 MariaDB git 存储库的提交权限的开发人员。但是，我们希望它对于任何想要为 MariaDB 贡献代码的人都有用，以了解审阅者对他们的期望。
这不是关于编码风格或是否应该优先选择 C 而不是 C++ 的话题。那应该是一个应该尽早创建的单独话题。
基础知识
在编码时，尽量创建“永远不需要再次更改”的代码。尽可能使代码具有最佳性能。通常，为了使代码比最初预期的快15％，可以花费50％的时间。在计划时间估计时，请考虑这一点！话虽如此，请勿尝试添加尚未使用的类或功能。
代码应易于阅读，并遵循项目的编码标准。比起复杂的解决方案，较小和较简单的补丁通常更好。在未与 Sergei 或 Monty 检查之前，请勿使服务器依赖于新的外部库！
对于任何不明显的内容，请添加代码注释。在可能的情况下，在代码中使用断言来记录参数等的期望。通常，如果代码需要复杂的注释，请考虑是否有更好的方法来构建逻辑。更简单通常更好，更少的 bug。
提交注释中应包含的内容
- Jira 问题编号和摘要，例如： MDEV-23839 innodb_fast_shutdown=0 hang on change buffer merge
- 一个空行
- 问题的简短描述
- 解决方案的描述
- 任何额外信息，以便理解补丁
- 提交消息应是自包含的，最好不需要审阅者完全查看 Jira 就能理解提交。这并不意味着提交消息应包括所有背景和考虑的不同设计选项，因为 Jira 应包含这些信息。
- 所有审阅者和作者的名称应清楚地在提交消息中列出。首选方式是（每个人一行）
- Reviewed-by: email
- Co-authored-by: email
- 有关详细信息，请参见 https://docs.github.com/en/free-pro-team@latest/github/committing-changes-to-your-project/creating-a-commit-with-multiple-authors。
- 默认情况下，所有代码都应进行审查。仅在非常特殊的情况下（例如合并（原始代码已经进行过审查）），才可以进行自我审查，这应在提交中清楚说明。在这种情况下，在推送之前，当然应特别小心地在本地和 buildbot 中测试代码。
测试
- 所有代码都应具有测试用例，以显示新代码是否有效，或者在修复错误的情况下，问题是否已解决！它应在未打补丁的服务器上失败，并在新版本中运行。在极端情况下，如果实际上不可能进行测试用例，则需要在提交消息中（可选地也在 Jira 中）记录代码的测试方法。
- 如果存在 Jira 问题，则测试用例应引用该问题。
- 与性能有关的补丁应由开发人员（对于简单的提交）或性能测试人员进行测试。结果应在 Jira 中列出，并在提交中进行概述。
- 复杂的补丁应由 QA 在推送之前的 bb- 分支中进行测试。Jira 条目应包括已完成的测试类型和运行的测试类型的信息。
- 对于任何不是微不足道的内容，应在新代码上运行 Valgrind 或 ASAN / MSAN。 （如果您无法让 valgrind 或 ASAN 正常工作，则 Buildbot 将为您执行此操作）。至少应通过其中一个测试用例。如果由于某种原因开发人员无法执行此操作，则应检查执行此操作的 buildbot 构建器，并确保至少其测试用例不会产生有关使用未初始化内存或其他故障的警告。
- 对于复杂的代码，开发人员最好使用 gcov 或某些类似工具，以确保至少不执行所有非错误分支。 “mtr --gcov” 或 “dgcov.pl” 可以帮助您完成此操作。
将代码推送到稳定分支之前
- 确保您已为新代码编译了所有内容，在调试服务器上（使用 cmake -DCMAKE_BUILD_TYPE=Debug 配置），包括受您的代码更改影响的所有嵌入式和所有插件。
- 使用调试服务器在本地运行 mysql-test-run（mtr）测试套件。
- 对于任何复杂的内容，都应运行完整的测试套件。
- 对于绝对微不足道的内容，至少必须运行主要套件。
- 总是首先推送到 bb- 分支以测试代码。当 buildbot 中的 bb- 分支为绿色时，可以推送到主分支。注意检查 Windows 构建是否编译（要特别注意检查，因为这经常失败），以及 valgrind 和 msan 构建是否显示与新测试用例相关的任何问题。
- 如果必须在推送之前进行变基，则必须从头开始。
- 在从第三方（如 MySQL）移植代码时，请确保将版权归属于正确的所有者，在每个修改后的文件头中。
- 例如： 版权所有（c）2000, 2018, Oracle 及/或其附属公司。 版权所有（c）2009, 2020, MariaDB
- 唯一的例外是，如果更改微不足道且变基微不足道且本地 mysql-test-run 已经工作，则可以直接推送到主分支。只有在您99％确定没有问题时才这样做！请不要让我们后悔我们做出了这个例外！ 当我们有受保护的 git 分支时，上述规则将自动执行，因为保护将处理此事。
开始新项目
- 首先创建一个 Jira 条目，解释问题以及可以用来解决问题的不同解决方案。如果有新的语法，请包括查询和结果的示例。
- 在获得要使用的解决方案的一致意见后，使用建议的解决方案详细说明 Jira 条目。
- 当架构得到审查后，分配的开发人员可以开始编码。
- 当代码准备好后，Jira 条目应与审阅人员进行更新。
- 审阅人员检查代码，要么批准将其推送，要么向应该修复的开发人员提供评论。在后一种情况下，开发人员更新代码并将其交还给审阅人员。这将继续进行，直到代码得到批准。
- 如果在项目期间更改设计，则需要更新 Jira 中的设计。
修复错误
- 确保 Jira 问题是最新的。
- 对于需要重新设计的复杂错误，请遵循“开始新项目”的过程。
- 对于较简单的错误，可以跳过列出不同解决方案和架构的步骤。但是，仍应在 JIRA 注释中记录错误原因以及如何修复或待修复。
使审阅人员工作更轻松
- 确保在请求审阅之前编译所有代码，并且所有 MTR 测试都能工作
- 尝试将较大的项目拆分为较小的、自包含的变更集。
- 自动化的事情，例如类、变量、函数等的重命名最好在单独的提交中完成。
审核代码时
请记住，任何项目的稳定性和安全性在很大程度上取决于审阅人员。如果已接受的补丁有问题，通常应该责备审阅人员，因为是审阅人员允许其进入的！
- 确保代码在 New BSD 或 MariaDB 的另一个经批准的许可证下获得许可（基本上是任何不与 GPL 冲突的开源许可证），或者贡献者已签署 MCA。
- 仅允许使用 MySQL 的代码使用 GPL（因为 MariaDB 已经依赖于 MySQL 代码）。
- 确保提交不太大。如果代码非常大，请提供如何将其拆分为较小部分的建议。合并提交（如果可以重建，则不允许合并提交）以保持历史线性。
- 检查提交消息是否正确描述了提交。对于改善性能的代码，请确保 Jira 和提交消息包含有关改进的信息。
- 检查旧测试中是否有未说明的更改。
- 检查代码质量（没有明显的错误，使用正确的算法）
- 检查是否可以简化或优化任何代码。使用已经存在的函数，循环是否最优，互斥锁是否使用正确等。
- 确保代码有适当的测试用例。请参阅“测试”以了解所需内容！
- 确保代码遵循 MariaDB 的编码标准。该文档应该很快就会创建，但在此期间，如果您不确定，请咨询旧的 MySQL/MariaDB 开发人员。
- 确保代码遵循在 Jira 中同意的架构（如果在 Jira 中）。
- 代码应易于理解（良好的代码注释，良好的函数和变量名称等）。
- 确保您理解审核的每一行代码。如果不是，请要求开发人员添加更多注释以澄清或向另一个审核人员寻求帮助。
- 所有常见情况都不会降低性能。
- 任何涉及任何敏感区域（文件、通信、登录、加密或安全）的代码都需要另一个是该领域专家的审核人员。
另请参阅
- 开发人员入门 (mariadb.org)
- 获取代码、构建、测试 (mariadb.org)
- 编写适用于 MariaDB Server 的良好测试用例 (mariadb.org)
- 提交拉取请求 (mariadb.org)
- 参与 MariaDB 项目（面向非开发人员）
Content reproduced on this site is the property of its respective owners,
and this content is not reviewed in advance by MariaDB. The views, information and opinions
expressed by this content do not necessarily represent those of MariaDB or any other party.
