新贡献者向导

新贡献者向导

这篇向导旨在给正在准备向 Dubbo 提交贡献的新手提供指导。

邮件列表描述

邮件列表是 Dubbo 官方推荐的讨论方式，所有与 Dubbo 相关的内容都可以在这里讨论，请点击 Issue 了解更多关于邮件列表订阅的内容

如需订阅如下邮件列表，请参考 邮件列表订阅向导

  • dev@dubbo.apache.org：开发邮件列表，您在使用或者开发 Dubbo 的过程中遇到的任何问题，都可以在这里进行提问。
  • commits@dubbo.apache.org：所有的提交内容都会推送到这个邮件列表，如果您对 Dubbo 的进展感兴趣，可以订阅这个邮件列表。
  • issues@dubbo.apache.org：所有的 JIRA Issues 和修改信息都会推送到这个邮件列表。Dubbo 社区已经决定使用 GitHub Issues 代替 JIRA Issues，因此大部分 Issues 将由 GitHub Issues 进行跟踪。JIRA Issues 用于跟踪 ASF 相关问题。

报告问题

贡献代码流程

此贡献流程适用于所有的 Apache Dubbo 社区内容，包括但不限于 dubbo（主干仓库）、dubbo-admin、dubbo-website。

以下以贡献 dubbo （主干仓库） 为例，详细说明贡献流程。

1. Fork apache/dubbo 项目到您的 GitHub 帐号下

2. 克隆您 Fork 的 Dubbo 代码仓库到您本地

git clone ${your fork dubbo repo address，for example：https://github.com/${your github id}/dubbo.git}
cd dubbo

3. 添加 apache/dubbo 仓库为 upstream 仓库

git remote add upstream https://github.com/apache/dubbo.git

git remote -v

    origin    ${your fork dubbo repo address} (fetch)
    origin    ${your fork dubbo repo address} (push)
    upstream    https://github.com/apache/dubbo.git (fetch)
    upstream    https://github.com/apache/dubbo.git (push)

git fetch origin
git fetch upstream

4. 我们的工作以 Issue 为驱动，认领个 Issue，或者创建一个 Issue 并描述清楚要做什么。

新人推荐标记为： good first issue 的 Issue

5. 选择一个开发的基础分支，通常是 master / 3.0 / 3.1，并基于此创建一个新的本地分支

  • 3.1 分支是 3.1 版本的开发分支
  • 3.0 分支是 3.0 版本的开发分支
  • master 分支是 2.7 版本的开发分支
# 从远程仓库创建分支到本地
git checkout -b up-dev-issue#${issue-number} upstream/master

为了避免一些不必要的麻烦，我们推荐以 “upstream” 中的分支为基础创建新的本地分支。 可以以要做的事情的简单描述作为分支名(只要你能看懂就行)，通常情况下我们会把 Issue 号包含到分支名中，例如上面的 checkout 命令中的。

6. 在本地新建的开发分支上进行各种修改

首先请保证您阅读并正确设置 Dubbo code style，相关内容请阅读 编码规范 。

修改时请保证该本地分支上的修改仅和 Issue 相关，并尽量细化，做到一个分支只修改一件事，一个PR只修改一件事。

可以在提交注释中添加 “#Issue号”，将该提交与 Issue 关联。

7. 将您开发完成后的分支，上传到您fork的仓库

git push origin up-dev-issue#${issue-number}

8. 创建 Pull Request

Dubbo 社区将会 Review 您的 Pull Request，并可能提出修改意见，您可以根据修改意见回到步骤6进行修改，并使用步骤7进行重新提交。

9. 如果没有问题，Dubbo 社区将会把您的修改合并，恭喜您成为 Dubbo 的贡献者。

特别说明:

  • 开源项目一般都是以分支的方式工作，每件事情都创建一个分支。
  • 创建分支时，不要从本地仓库里的分支里创建，而是从指向主仓库的远程仓库创建。
  • 不要一直在同一个分支工作， 一个分支只做一件事情，不要在同一个分支做多件事情。
  • 一直在同一分支中修改，提交都会一直在该分支中。这样就会造成每次PR都会带着之前的所有被 merge、未被 merge 的提交。
  • 一件事情可以是一个 Issue，也可以是一个 Issue 中的部分 （Issue 太大可以拆解）。
  • 一个分支（一件事情）只提一个PR。
  • 提了 PR 后，如果 PR 有问题需要修改，可以继续在这个 PR 关联的分支修改提交。在 PR 被 merge 前，向这个分支继提交都会进入这个 PR。
  • 如果只是想纯更新代码，可以从主仓库提 PR 到你fork的仓库，源选择主仓库里的分支，目标选你 fork 的仓库的分支。
  • 这种方式更新代码，你 Fork 的仓库中会多一个提交。如果以你 Fork 的仓库中的分支为源创建分支， 这个提交纪录会被带过去并出现在PR中，所以要以主仓库的分支为源创建分支。
  • Issue 认领: 在要认领的 Issue 中回复，明确表式你将处理这个 Issue。这样社区的 PMC 和 Committer 会把该 Issue assign 给你。当然认领前先看下这个 Issue 有没有被别人认领了。 为了方便，我们可以把认领的回复统一为: @i will solve it@， 当然这不是必须的。

编码规范

请按照 CONTRIBUTING.md 中的编码规范对自己的代码进行检查。

代码约定

我们的代码风格几乎和标准 Java 约定一致（流行IDE的默认设置满足这一点），主要有以下附加限制：

  • 如果当前行中有超过 120 个字符，则起一个新的行。
  • 确保所有新的 .java 文件都有一个简单的 JavaDoc 类注释，最好至少有一个关于该类的解释说明。
  • 将ASF许可注释添加到所有新的 .java 文件（从项目中的现有文件复制）
  • 请确保没有将 @author 标记添加到您所贡献的文件中，因为 Apache 不使用 @author 标记，其他方式（如 CVS、Git）将公平地记录所有您的贡献。
  • 为代码添加一些 JavaDoc，如果您更改命名空间，则需要一些 XSD DOC 元素。
  • 对于新的特征或重要的修复程序，应该添加单元测试。
  • 如果没有其他人使用您的分支，请将它与 master（或主项目中的其他目标分支）同步。
  • 当编写提交消息时，请遵循这些约定，如果您正在修复一个现有问题，请在提交消息的末尾添加 Fixes XXX（其中XXX是问题编号）。
代码风格

我们提供了 IntelliJ idea 的模版文件 dubbo根目录/codestyle/dubbo_codestyle_for_idea.xml，您可以将它导入到IDE。 如果使用 Eclipse，可以通过参考该文件手动配置。

代码风格检查:

  1. 安装 checkstyle 插件(IDEA可以在插件市场搜索)
  2. 插件安装好后，在IDEA的settings==>tool==>checkstyle中设置: checkstyle1 checkstyle2 checkstyle3 checkstyle4

注意事项

使用 dubbo_codestyle_for_idea.xml 为你的 IDEA 设置代码格式是贡献代码前至关重要的一个步骤，否则你将会无法通过 CI 的代码风格校验，下面几个步骤给你演示了如何配置代码格式：

  1. 进入菜单页 Editor > Code Style
  2. 在 Code Style 页面的 scheme 菜单中点击 manage profiles 选项 在下拉列表中选择 Import Scheme， 接着选择 IntelliJ IDEA code style XML 导入 xml 文件
  3. 输入你的格式名称，方便在不同工程之间进行识别，最后别忘了 ⏎ 来保存更改. 设置完成后，IDEA 会帮助你自动 reformat 代码

参与发布投票

参与发布投票是一种重要的贡献社区的方式，Dubbo 社区非常欢迎和鼓励任何人参与投票，每当一个版本需要正式发布的时候，会在开发者邮件列表上进行发布投票，只有当投票取得通过之后，才会正式发布，可以参考这个 检查列表 对源码进行合规性检查。如果有任何问题，可以在开发者邮件列表上提问。

最后修改 March 1, 2023: Add /zh/ docs aliases (#2336) (f2070b3fdd)