新贡献者向导

这篇向导旨在给正在准备向 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.1, 并基于此创建一个新的本地分支

master/3.1 分支是目前 3.1 版本的开发分支

# 从远程仓库创建分支到本地
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)将公平地记录所有您的贡献。
  • 为代码添加一些 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 社区非常欢迎和鼓励任何人参与投票,每当一个版本需要正式发布的时候,会在开发者邮件列表上进行发布投票,只有当投票取得通过之后,才会正式发布,可以参考这个检查列表对源码进行合规性检查。如果有任何问题,可以在开发者邮件列表上提问。


Last modified February 22, 2023: Merge refactor website (#2293) (4517e8c1c9)