Contributor 指南 on Apache Dubbo

如何成为 Dubbo Committer

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

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

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

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

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

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

我可以贡献什么？

请参阅新的贡献者指南。

新贡献者向导

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 相关问题。

报告问题

非安全问题直接在 GitHub Issue 中提出，另请参考 Issue Template 。
安全问题请参考 “反馈漏洞” 。

贡献代码流程

此贡献流程适用于所有的 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

邮件列表订阅向导

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，就会有人回答您的问题。

报告安全问题

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

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

报告漏洞

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

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

漏洞处理

漏洞处理过程的概述是：

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

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

软件捐献向导

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

扩展 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 组的成员会对您的项目进行代码审查。随后，您可以对这些代码进行改进。

测试覆盖率向导

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