代码贡献

简介

Neo4j 社区是一个围绕 Neo4j 图数据库的软件和组件的免费软件和开源社区。它由 Neo Technology 赞助，该公司提供基础设施（不同类型的托管、文档等）以及人员来管理它。Neo4j 社区是一个开放的社区，因为它欢迎任何接受基本贡献标准的成员。

贡献可以有多种形式（文档、讨论、错误报告）。本文档概述了代码贡献者的治理规则。

治理基础

简而言之，如果您希望贡献代码，则需要了解以下基本知识

  • Neo4j 项目发布的所有软件都必须在 Neo4j 代码 贡献者许可协议 下贡献。

  • Neo4j 是一个免费软件和开源社区。作为贡献者，您可以将您的工作置于已由 自由软件基金会 或 开源计划 批准的任何许可证下。您仍然保留版权，因此除了该许可证之外，您当然可以根据任何其他许可证（例如完全专有许可证）发布您的作品，只是不能在 Neo4j 基础设施上发布。

  • Neo4j 软件分为多个组件。一个 Git 存储库包含一个或多个组件。

  • 源代码应遵循 Neo4j 代码风格，并在合理范围内“融入”Neo4j 基础设施，具体取决于特定组件。

贡献者角色

每个贡献代码的个人都以角色的上下文进行贡献（一个个人可以有多个角色）。角色定义了他们的责任和权限

  • 补丁提交者 是希望向现有组件贡献补丁的人员。请参见下面的 贡献工作流程。

  • 提交者 可以直接向一个或多个组件贡献代码。

  • 组件维护者 负责特定组件。他们可以

    • 在他们组件的存储库中提交代码，

    • 管理存储库的工单，

    • 授予存储库的推送权限。

  • Neo4j 管理员 管理 Neo4j 基础设施。他们

    • 定义新的组件并分配组件维护权，

    • 推动、指导和指导 Neo4j 组件开发。

贡献工作流程

对 Neo4j 的代码贡献通常通过 Github 拉取请求完成，遵循以下所示的工作流程。在发送拉取请求之前，请查看 拉取请求检查清单。

  1. 分叉相应的 GitHub 存储库。

  2. 为您的特定功能或修复创建一个新分支。

  3. 为您的代码编写单元测试，即使是小的贡献也要编写。.

  4. 编写代码.

  5. 编写相应的 Javadoc 和 Neo4j 手册中的条目。

  6. 提交更改.

  7. 发送拉取请求.

拉取请求检查清单

  1. 签署 CLA.

  2. 确保您没有添加任何合并提交.

  3. 针对最新的 master 分支进行变基.

  4. 运行所有相关的测试.

  5. 发送请求！

单元测试

如果您为我们提供了覆盖您编写的代码的小型、可读的单元测试，那么您的更改被接受的机会会更高。此外，请确保您的代码不会破坏任何现有的测试。请注意，根据您更改的内容，可能还需要测试下游组件，。

要运行测试，请使用 Maven 而不是您的 IDE，以确保其他人可以复制您的测试运行。在任何给定组件中运行 Neo4j 测试的命令是 mvn clean test。

单元测试的总体结构如下所示

@Test
public void myTest()
{
    // Given
    [ Setup code here, setting the stage and
      parameters that are relevant ]

    // When
    [ The code that is being tested, preferably
      just one line, like calling a method ]

    // Then
    [ Assertions on the result ]
}

代码风格

Neo4j 代码风格维护在 http://neo4j.github.io/。

提交消息

请在提供良好的提交消息时多加注意；可以在 http://chris.beams.io/posts/git-commit/ 找到关于良好实践的优秀总结。请同时考虑以下指南

  • 使用英语。这包括正确的标点符号和拼写。提交消息应该能够一目了然地传达一些信息——它们不是聊天室。

  • 请记住，提交是一个更改集，它描述了跨多个文件的连贯更改集。尝试将每个提交作为一个逻辑更改进行分组。解释它更改了什么。如果您必须重做工作，您可能需要在进行拉取请求之前清理您的提交日志。

  • 如果您修复了与工单相关的错误或问题，请在消息中引用该工单。例如，“添加了这个然后更改了那个。这修复了 #14。” 仅在提交中提及 #xxx 将将其连接到具有该编号的 GitHub 问题，请参阅 GitHub 问题。以下任何同义词也将起作用

    • 修复 #xxx

    • 已修复 #xxx

    • 修复 #xxx

    • 关闭 #xxx

    • 关闭 #xxx

    • 已关闭 #xxx。

  • 请记住传达意图。不要过于简短，也不要提供太多细节。这就是 git diff 的作用。

签署 CLA

贡献的一个关键方面是 贡献者许可协议。简而言之：请确保签署 CLA，否则 Neo4j 项目将无法接受您的贡献。

不要合并，而是使用变基！

因为我们希望每个贡献都包含在一个提交中，所以拉取请求中不允许合并提交。合并很混乱，并且应该只在必要时进行，例如，当将分支合并到 master 以记住代码来自何处时。

如果您想更新您的开发分支以合并来自 master 的最新更改，请使用 git rebase。有关如何使用变基的详细信息，请参阅 Git 手册中的变基内容：Git 手册。