Apache Dubbo – Contributor 指南

Contribution-Guidelines: 如何成为 Dubbo Committer

Mon, 01 Jan 0001 00:00:00 +0000

每个人都可以成为 Apache 项目的贡献者。作为一个贡献者只是意味着你对项目感兴趣并以某种方式做出贡献，从提出合理的问题（这些问题记录了项目并向开发人员提供反馈）到提供新的特性作为补丁。

如果你成为对一个项目有价值的贡献者，你有可能被邀请成为一个 committer。committer 是 ASF（Apache软件基金会）中用来表示提交特定项目的人的术语。它给你带来对项目仓库和资源写的权限。

在 Dubbo 社区，如果一个 committer 获得大量的优秀成绩，就可以被邀请加入项目管理委员会（PMC）。

当您不熟悉ASF使用的开源的开发过程时，有时难以理解的一点，就是我们更重视社区而不是代码。一个强大而健康的社区将受到尊重，成为一个有趣和有益的地方。更重要的是，一个多元化和健康的社区可以长时间的持续支持代码，即使个别公司在这个领域来来往往，也是如此。

更多详细信息可以在这里找到。

我可以贡献什么？

请参阅新的贡献者指南。

Contribution-Guidelines: CLA 签署向导

Mon, 01 Jan 0001 00:00:00 +0000

以下情况，需要您签署 Apache ICLA：

在 Dubbo 被捐赠给 Apache 之前，您已经为 Dubbo 作出了很多贡献，并且您以前没有签署过 Alibaba-CLA。
您已经为 Dubbo 作出了很多贡献，并且您被邀请成为 Dubbo 提交者，且之前没有签署过 Alibaba-CLA 或者 Apache ICLA。

步骤

下载这篇 pdf 文档
编辑该文档，在必要的空格处填上适当的内容
打印
在打印好的文件上签字
扫描
发送一封邮件到secretary@apache.org，并抄送给private@dubbo.apache.org：
- 邮件标题为“ICLA submission”
- 请在邮件正文附上您的github账号链接
- 请记得将您的ICLA文档放入邮件的附件里

空格填写必要说明

Mailing address：首选英文格式的公司地址
preferred apache id(s)：如果您被邀请成为一名提交者，那么需要您填写一个apache账号，否则，可以不填
notify project：Dubbo（意思就是Dubbo就是通知您签署ICLA的项目）

Contribution-Guidelines: 新贡献者向导

Mon, 01 Jan 0001 00:00:00 +0000

这篇向导旨在给正在准备向 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. 选择一个开发的基础分支，通常是 upstream/master，并基于此创建一个新的本地分支

upstream/master 分支是目前 2.7.x 版本的开发分支

# 从远程仓库创建分支到本地
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

参考pull request template中的检查列表

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，可以通过参考该文件手动配置。

代码风格检查:

安装 checkstyle 插件(IDEA可以在插件市场搜索)
插件安装好后，在IDEA的settings==>tool==>checkstyle中设置:

注意事项

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

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

参与发布投票

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

Contribution-Guidelines: 邮件列表订阅向导

Mon, 01 Jan 0001 00:00:00 +0000

Apache incubator 的 Dubbo 开发者邮件列表（dev@dubbo.apache.org）已经建立，请随时订阅并参考[^1]获取更多细节。

你也可以直接查看历史邮件

下面是一个关于 Dubbo 邮件列表订阅的简短指南：

发一封邮件到 dev-subscribe@dubbo.apache.org，其内容和标题均可为空。随后，您会收到一封邮件，其内容如下：

from: dev-help@dubbo.apache.org
reply-to: dev-sc.xxxxxxx.xxxxxxxx-hello=example.com@dubbo.apache.org
to: hello@example.com
date: Sat, Feb 24, 2018 at 3:12 PM
subject: confirm subscribe to dev@dubbo.apache.org
mailed-by: apache.org
Hi! This is the ezmlm program. I'm managing the
dev@dubbo.apache.org mailing list.
I'm working for my owner, who can be reached
at dev-owner@dubbo.apache.org.
To confirm that you would like
hello@example.com
added to the dev mailing list, please send
a short reply to this address:
dev-sc.xxxxxxx.xxxxxxxx-hello=example.com@dubbo.apache.org
Usually, this happens when you just hit the "reply" button.
If this does not work, simply copy the address and paste it into
the "To:" field of a new message.
or click here:
mailto:dev-sc.xxxxxxx.xxxxxxxx-hello=example.com@dubbo.apache.org
...

直接回复邮件，其内容和标题仍然可以为空，随后，您将再次收到一封邮件，其内容如下：

from: dev-help@dubbo.apache.org
to: hello@example.com
date: Sat, Feb 24, 2018 at 3:14 PM
subject: WELCOME to dev@dubbo.apache.org
mailed-by: apache.org
Hi! This is the ezmlm program. I'm managing the
dev@dubbo.apache.org mailing list.
I'm working for my owner, who can be reached
at dev-owner@dubbo.apache.org.
Acknowledgment: I have added the address
hello@example.com
to the dev mailing list.
Welcome to dev@dubbo.apache.org!
Please save this message so that you know the address you are
subscribed under, in case you later want to unsubscribe or change your
subscription address.
...

到此，邮件列表订阅完毕，从现在开始，您将收到很多发送到该邮件列表的邮件，如果您有更多的问题，只需发送邮件到dev@dubbo.apache.org，就会有人回答您的问题。
如果您想取消订阅，只需发送一封邮件到dev-unsubscribe@dubbo.apache.org，收到回复后，请按其指定步骤执行。

请注意：dev@dubbo.apache.org和dev@dubbo.apache.org都是有效的, 您可以订阅它们中的任何一个。

[^1] http://apache.org/foundation/mailinglists.html#subscribing

Contribution-Guidelines: 报告安全问题

Mon, 01 Jan 0001 00:00:00 +0000

Apache Software Foundation 在消除其软件项目中的安全性问题方面采取严格的立场。Apache Dubbo 对与其功能和特性有关的问题非常敏感并很快提出。

报告漏洞

如果您对 Dubbo 的安全性有担心，或者发现漏洞或潜在威胁，请发送电子邮件至 security@dubbo.apache.org 与 Apache Dubbo 安全团队联系。在邮件中，指定问题或潜在威胁的描述。还敦促您推荐重现和复制问题的方法。Dubbo 社区会在评估和分析调查结果之后与您联系。

请先注意在安全电子邮件中报告安全问题，然后再在公共领域公开该问题。

漏洞处理

漏洞处理过程的概述是：

报告者将漏洞秘密报告给 Apache。
相应项目的安全团队与报告者私下合作来解决漏洞。
制作了包含该修复程序的有关 Apache 产品的新版本。
该漏洞已公开宣布。

有关此过程的详细说明，请参见此处

Contribution-Guidelines: 软件捐献向导

Mon, 01 Jan 0001 00:00:00 +0000

在您阅读这篇指南之前，请确保您已经向PMC确认了实际需要的 SGA。

如果您向 Apache Dubbo 捐赠了大量的代码或文档，则需要在合并代码或者文档之前签署软件授权书。

操作步骤

下载这篇pdf文档
打印下载好的文档
按要求填充表格（请看下边示例）
请您的领导在上边签字
扫描
将扫描好的文档以邮件的方式发送给secretary@apache.org，并抄送给private@dubbo.apache.org

示例

下边是一个文本示例，原始文本可以在这里找到

License Agreement
This License Agreement is entered into as of the _12th_ day of
___April____, __2018__ by ___ABC Software Co., Ltd.____ ("Licensor"),
in favor of The Apache Software Foundation, a Delaware nonstock
membership corporation (the "Foundation").
WHEREAS, Licensor owns or has sufficient rights to contribute the
software source code and other related intellectual property as
itemized on Exhibit A ("Software") under the terms of this agreement
to the Foundation for use within Foundation software development
projects ("Projects").
NOW, THEREFORE, FOR GOOD AND VALUABLE CONSIDERATION, the receipt
and legal sufficiency of which are hereby acknowledged, the parties
hereto, intending to be legally bound, agree as follows:
1. Subject to the terms and conditions of this License, Licensor
hereby grants to the Foundation:
a) a non-exclusive, worldwide, royalty-free, irrevocable
copyright license to reproduce, prepare derivative works of,
publicly display, publicly perform, distribute and sublicense,
internally and externally, the Software and such derivative
works, in source code and object code form; and,
b) a non-exclusive, worldwide, royalty-free, irrevocable
patent license under Licensed Patents to make, use, sell,
offer to sell, import and otherwise transfer the Software
in source code and object code form. "Licensed Patents" mean
patent claims owned by Licensor which are necessarily
infringed by the use or sale of the Software alone.
2. Licensor represents that, to Licensor's knowledge, Licensor is
legally entitled to grant the above license. Licensor agrees to notify
the Foundation of any facts or circumstances of which Licensor becomes
aware and which makes or would make Licensor's representations in this
License Agreement inaccurate in any respect.
3. This Software is provided AS-IS, WITHOUT WARRANTIES OR CONDITIONS
OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, WITHOUT LIMITATION,
ANY WARRANTIES OR CONDITIONS OF TITLE, NON-INFRINGEMENT, MERCHANTABILITY
OR FITNESS FOR A PARTICULAR PURPOSE. NEITHER THE LICENSOR NOR ITS
SUPPLIERS WILL BE LIABLE TO THE FOUNDATION OR ITS LICENSEES FOR ANY
DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
DAMAGES (INCLUDING WITHOUT LIMITATION LOST PROFITS), HOWEVER CAUSED
AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF
THE USE OR DISTRIBUTION OF THE WORK OR THE EXERCISE OF ANY RIGHTS
GRANTED HEREUNDER, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
This License Agreement is the entire agreement of the parties
with respect to its subject matter, and may only be amended by a
writing signed by each party. This License Agreement may be
executed in one or more counterparts, each of which shall be
considered an original.
IN WITNESS WHEREOF, Licensor has executed this License Agreement
as of the date first written above.
LICENSOR:
Signed By: _____________________________________ <--- Your boss's sign here
Print Name: _____Lei Li_________________________ <--- Your boss's name here
Title: ____Director_____________________________ <--- Your boss's title here
Representing: ____ABC Software Co., Ltd. _______
________________________________________________
Contact Name: ____Lei Li________________________ <--- Your boss's name here
Contact Email: ____lilei@abc.com________________ <--- Your boss's email here
Exhibit A
List of software and other intellectual property covered by this agreement:
* Github address where your code is hosted
* Pull request link

Contribution-Guidelines: 扩展 Dubbo 向导

Mon, 01 Jan 0001 00:00:00 +0000

Dubbo 使用微内核+插件的设计模式。内核只负责组装插件，Dubbo 的功能都是由扩展点（插件）实现，这就意味着 Dubbo 的所有功能都可以被用户定制的扩展所替代。

Dubbo 生态系统

我们建议您将扩展加入到 Dubbo 生态系统。使用这种模式，可以使 Dubbo 的核心仓库更干净，并且可以减少维护工作。更少的代码也可以提高核心仓库的构建速度。

依赖

要实现您自己的 Dubbo 扩展，通常只需依赖 API jar 就可以满足您的需求。例如：

<dependency>
<groupId>org.apache.dubbo</groupId>
<artifactId>dubbo-serialization-api</artifactId>
<version>${dubbo.version}</version>
</dependency>

Src指导

通常，要实现特殊的扩展，只需要参考开发者指南，实现Dubbo必要的接口和合适的扩展即可。除此之外，还有一些其它的事项需要注意：

良好的测试，您需要编写单元测试和冒烟测试以消除潜在的 bug。
没有警告，如有不可避免的警告，请使用 @SuppressWarnings 阻止它，但是请不要乱用。
README。添加必要的自述以说明如何使用扩展，以及需要注意的事项。
许可证：请确保使用Apache License 2.0。

通知社区

提交您的代码到 github。
加入邮件列表（建议）。点击这里查看如何加入邮件列表。
发送一封邮件到 dev@incubator.dubbo.apache.org 通知社区。
通常，发送邮件之后，社区会对您的扩展进行讨论，dubbo 组的管理员会联系您转移您的项目到 dubbo 生态系统。

转移项目到dubbo生态系统

dubbo 组的管理员会请您将您的项目的所有者转让给 dubbo。
dubbo 组的管理员会在 dubbo 组下新建一个项目并邀请您加入到这个项目。
一旦您接受邀请，您可以将您的项目转移到 dubbo 组下的新项目里。
dubbo 组的成员会对您的项目进行代码审查。随后，您可以对这些代码进行改进。

Contribution-Guidelines: 测试覆盖率向导

Mon, 01 Jan 0001 00:00:00 +0000

写单元测试的收益

单元测试能帮助每个人深入代码细节，了解代码的功能。
通过测试用例我们能发现bug，并提交代码的健壮性。
测试用例同时也是代码的demo用法。

单元测试用例的一些设计原则

应该精心设计好步骤，颗粒度和组合条件。
注意边界条件。
单元测试也应该好好设计，不要写无用的代码。
当你发现一个方法很难写单元测试时，如果可以确认这个方法是臭代码，那么就和开发者一起重构它。
Dubbo中用的mock框架是: mockito. 下面是一些开发向导:mockito tutorial,mockito refcard
TDD（可选）：当你开始写一个新的功能时，你可以试着先写测试用例。

测试覆盖率设定值

在现阶段，Delta更改代码的测试覆盖设定值为：>＝60%，越高越好。
我们可以在这个页面中看到测试报告: https://codecov.io/gh/apache/dubbo

Apache Dubbo – Contributor 指南

Contribution-Guidelines: 如何成为 Dubbo Committer

我可以贡献什么？

Contribution-Guidelines: CLA 签署向导

步骤

空格填写必要说明

Contribution-Guidelines: 新贡献者向导

邮件列表描述

报告问题

贡献代码

贡献流程

1. fork Apache/Dubbo 项目到您的github帐号下

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

3. 添加Apache/Dubbo仓库为upstream仓库

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

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

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

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

8. 创建 pull request

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

特别说明:

编码规范

代码约定

代码风格

参与发布投票

Contribution-Guidelines: 邮件列表订阅向导

Contribution-Guidelines: 报告安全问题

报告漏洞

漏洞处理

Contribution-Guidelines: 软件捐献向导

操作步骤

示例

Contribution-Guidelines: 扩展 Dubbo 向导

Dubbo 生态系统

依赖

Src指导

通知社区

转移项目到dubbo生态系统

Contribution-Guidelines: 测试覆盖率向导

写单元测试的收益

单元测试用例的一些设计原则

测试覆盖率设定值

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