跳至内容

开发

以下部分描述了JanusGraph的开发流程。

Development Decisions

许多开发决策将在JanusGraph贡献者的日常工作中做出，无需额外的流程开销。然而，对于较大的工作体量和重要的更新与添加，应遵循以下流程。重要工作可能包括但不限于：

  • 一个主要的新功能或子项目，例如一个新的存储适配器
  • 增加核心依赖项的版本，例如Apache TinkerPop
  • 公共API的添加或弃用
  • 内部共享数据结构或API变更
  • 添加新的主要依赖项

对于这类变更，贡献者将：

  • 在GitHub问题跟踪器中创建一个或多个问题
  • 在janusgraph-dev邮件列表上发起一个DISCUSS讨论线程，以便提交者和其他社区成员可以讨论提议的更改
  • 当提议者认为适当时，应发起投票
  • 需要两个+1投票才能接受更改

分支

对于仅涉及一名开发者的功能特性，开发者将在他们自己的JanusGraph分支中工作，管理自己的分支，并在准备就绪时提交拉取请求。如果多名开发者希望协作开发某个功能，他们可以请求在JanusGraph仓库中创建一个功能分支。如果这些开发者不是提交者，将会指派一名JanusGraph提交者作为该分支的负责人。负责人将负责将拉取请求合并到该分支。

分支命名规范

所有托管在JanusGraph仓库中的分支名称都应前缀为Issue_#_。

拉取请求

希望为JanusGraph贡献的用户应当先fork JanusGraph仓库， 然后通过 GitHub pull request流程 提交拉取请求。 每个拉取请求必须关联一个现有议题。请确保 在拉取请求标题中包含相关议题编号， 完成拉取请求模板清单，并提供 用于验证拉取请求的测试套件描述。 拉取请求的提交信息应清晰描述完成的工作内容。 进行中的中间提交应在提交拉取请求前进行压缩合并。

审查后提交 (RTC)

拉取请求在合并前必须经过审查，遵循先审查后提交（RTC）流程。JanusGraph项目使用 GitHub审查流程 来审查拉取请求。非常欢迎并鼓励非提交者审查拉取请求。他们的审查虽不具备约束力，但可以作为参考，并且仍然是社区非常有价值的输入。以下规则适用于投票流程。

  • Approval flows
    • 合并拉取请求需要2位提交者批准
    • 如果提交者提交了拉取请求，则视为已获得其默认批准，因此还需要另外1位提交者的批准
    • 1 位提交者批准后，经过一周的审查期以听取异议，届时将默认采用惰性共识机制
  • 在变更请求中出现一个或多个-1投票将否决该拉取请求，直到所提及的问题得到解决且-1投票被撤回为止
  • 没有解释的变更请求将不被视为有效

提交后审查 (CTR)

在提交者认为完整RTC流程不必要的情况下，可以采用先提交后审查（CTR）流程。调用CTR的目的是减轻提交者的负担，并最小化合并琐碎更改的周转时间。这类更改可能包括：

  • 文档拼写错误或小型文档补充
  • 新增一个测试用例
  • 将已批准的更改反向移植到其他发布分支

任何遵循CTR提交的提交都应在提交注释中包含其为CTR的事实。希望审查CTR的社区成员可以订阅JanusGraph commits列表，以便在CTR提交时能够看到。如果另一位提交者回应-1，则应回滚该提交并遵循正式的RTC流程。

启用自动反向移植

在合并拉取请求之前，应决定是否应将贡献反向移植到其他发布分支。 对于大多数非破坏性更改来说，这应该是适用的。 如果更改适用于其他仍受支持的发布分支上完全不存在的内容，例如更新仅在master上引入的依赖项，或是在master上添加/大幅修改的代码，那么 反向移植将无法工作或需要过多精力。 否则，应在拉取请求合并之前添加适当的反向移植标签（例如，对于分支v0.6使用backport/v0.6）， 因为这允许反向移植操作自动处理反向移植。

合并拉取请求

当拉取请求获得批准后，即可准备合并（参见 Review-Then-Commit (RTC)）。 可以通过git命令手动合并，或通过GitHub界面进行合并。

对于需要向后移植的拉取请求（参见启用自动向后移植），向后移植操作应在拉取请求合并后创建一个拉取请求，将更改移植到其他发布分支。合并拉取请求的提交者应确保此自动向后移植成功。在出现合并冲突的情况下可能会失败。在这种情况下，需要手动执行向后移植。

手动向后移植

Backport CLI 工具可用于手动回移植一个拉取请求。 当拉取请求的自动回移植失败时，可能需要手动操作。 安装 CLI 工具后，还需要使用 GitHub 访问令牌进行配置。 这在 Backport CLI 工具的 README.md 中有详细说明。

然后你可以使用该工具回溯拉取请求 #xyz：

 backport --pr xyz

这将检出代码库，将拉取请求中的更改应用到相应的发布分支（如v0.6），然后要求您解决任何合并冲突。 在合并冲突解决后，它将创建一个反向移植更改的拉取请求。 请注意，在所有自动检查执行完毕后，这样的反向移植拉取请求通常可以通过CTR进行合并。 如果需要非平凡的更改来解决合并冲突，那么在合并拉取请求之前等待审查可能仍然是有意义的。

当然也可以使用 cherry-picking 手动将提交应用到不同的发布分支，而不是使用这个 CLI 工具。

发布策略

任何JanusGraph提交者都可以提议发布版本。要提议发布版本， 只需在 janusgraph-dev 上开启一个新的RELEASE讨论串， 提议新版本并请求关于发布内容应包括哪些的反馈。达成共识后， 发布经理将执行以下任务：

  • 创建一个发布分支，以便可以在master上继续工作
  • 准备发布制品
  • 在janusgraph-dev上发起投票批准发布
  • 提交者将有72小时的时间来审查和投票发布制品
  • 发布版本需要获得三个+1投票才能被批准
  • 一个或多个带有解释的-1投票将否决该发布，直到所提及的问题得到解决且-1投票被撤回

构建 JanusGraph

要构建JanusGraph，你需要git和Maven。

  1. 从GitHub克隆JanusGraph仓库到本地目录。

  2. 在该目录下，执行 mvn clean install。这将构建 JanusGraph 并运行内部测试套件。内部测试套件 没有外部依赖。请注意，运行所有测试用例 需要大量时间。要在构建 JanusGraph 时跳过测试，请执行 mvn clean install -DskipTests

  3. 为了全面的测试覆盖，执行 mvn clean test -P comprehensive。这将运行额外的测试， 覆盖与外部存储后端的通信、性能测试和并发测试。全面测试套件使用 HBase作为外部数据库，并要求已安装HBase。 请注意，运行全面测试套件需要相当长的时间（> 1小时）。

常见问题解答

Maven构建导致大量"[WARNING] We have a duplicate…"错误

确保在构建或依赖JanusGraph时使用maven-assembly-plugin。