跳到主要内容

贡献指南

Doubao 中英对照 Contribution Guidelines

从源码构建​

我们优先使用 Java 25 进行构建，因为我们借助 JSpecify 来校验源代码中的可空性约束。

不过，如果您因某种原因无法使用 Java 25，仍可使用 Java 17 在本地构建。在这种情况下，可空性约束不会在本地校验，而是通过持续集成的 Pull Request 工作流进行校验。

代码格式化与 Javadoc​

在提交 PR 之前，请运行以下命令，以确保格式正确并完成 Javadoc 处理

./mvnw spring-javaformat:apply javadoc:javadoc -Pjavadoc

-Pjavadoc 是一个用于启用 Javadoc 处理的 profile，以避免开发时漫长的构建时间。

备注

我们使用 Spring JavaFormat 项目来应用代码格式化约定，并对我们的许多代码规范执行 checkstyle 规则。

当安装格式化插件后，也可以在您的 IDE 中格式化代码。

贡献新的 gRPC 特性​

要贡献新特性，请遵循以下步骤：

  1. 实现自动配置与 Spring Boot 起步依赖：此步骤需要创建必要的自动配置和 Spring Boot 起步依赖，以便在 Spring Boot 应用程序中轻松实例化新模型。

  2. 编写测试：所有新类都应配有全面的测试。现有测试可作为构建和实现测试的有用参考。

  3. 为您的贡献编写文档：确保文档遵循既有格式，并使用 spring-javaformat 插件格式化代码和 Javadoc 注释。

通过遵循这些准则，我们可以在遵循统一实现与文档模式的同时，大幅扩展框架所支持的模型范围。

如何贡献​

讨论​

如果您有问题，请使用 grpc-java 标签查看 StackOverflow。查找现有的讨论，必要时发起新的讨论。

如果您怀疑存在问题，请在 Spring gRPC 项目的 GitHub issue 跟踪器中使用几个不同的关键词进行搜索。当您找到以往或当前的相关问题与讨论时，既有助于您学习，也有助于我们做出决策。

创建工单​

报告问题或提出特性请求是参与贡献的绝佳方式。您的反馈以及由此产生的交流能够源源不断地带来新思路。

在创建工单之前，请先花时间进行调研。

如果是在 StackOverflow 或邮件列表上讨论之后再创建工单，请在工单中提供一份自足完整的描述。我们知道这会增加额外工作，但 issue 跟踪器是记录设计讨论与决策的重要场所，这些记录在发布修复版本之后很久仍会被频繁引用，例如用于重新审视决策、了解某个特性的由来等。

准备好后，请在 GitHub 上创建工单。

工单生命周期​

问题刚创建时可能尚未指派，也没有修复版本。一两天内，该问题会被指派给某位特定的提交者。提交者随后会审查该问题，必要时要求提供更多信息，并根据审查结果为其指派修复版本或予以驳回。

修复准备就绪后，该问题会被标记为"Resolved（已解决）"，但仍可能被重新打开。修复发布后，如有必要，您需要创建一个新的相关工单并附上全新的描述。

提交 Pull Request​

您可以通过提交 Pull Request 来贡献源代码变更。

  1. 您必须有权提交代码变更。Spring gRPC 遵循开发者原产地证书（DCO）规则。提交信息必须包含一行 Signed-off-by。Git 甚至提供了 -s 命令行选项，可自动将其附加到您的提交信息中：

    This is my commit message

    Signed-off-by: Random J Developer <random@developer.example.org>

    [resolves #1234]

    提交 Pull Request 时，系统也会自动提醒您。

  2. 除最琐碎的贡献外，请为所有贡献创建工单。工单的目的是理解并讨论其背后的问题或特性。我们将 GitHub issue 跟踪器作为记录讨论与结论的首选场所。从这个意义上说，PR 下方的讨论更侧重于实现细节，且具有临时性。

  3. 请始终检出 main 分支，并基于该分支提交 Pull Request。对早期版本的回溯移植将根据具体情况逐一考虑，并在 issue 跟踪器中体现为修复版本。

  4. 使用简短的分支名，最好基于 GitHub issue（例如 gh-1234），否则就使用简洁的、小写、以连字符（-）分隔的名称，例如 fix-warnings。

  5. 有意识地选择提交的粒度，并将代表同一逻辑变更的多次编辑或修正合并（squash）为一次提交。有关精简提交历史的概述，请参阅 Pro Git 的「重写历史」一节。

  6. 按照以下规范格式化提交信息：主题行 55 个字符，描述 72 行，其后附上相关 issue，例如 [resolves #1234]。有关提交信息的最佳实践，请参阅 Pro Git 的「提交准则」一节，并使用 git log 查看一些示例。

  7. 在 PR 描述中列出 GitHub issue 编号。

如果您的贡献被接受，在合并之前可能会根据需要对其进行大幅修改。只要您的大部分变更保持完整，您的 Git 提交很可能仍会保留作者署名。您也可能被要求修改提交内容。

如果被要求进行修正，只需将变更推送到同一分支，您的 Pull Request 就会随之更新。换句话说，当被要求修改时，您无需创建新的 Pull Request。