跳到内容

开发

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

开发决策

在 JanusGraph 贡献者日常工作中，许多开发决策将在没有任何额外流程开销的情况下做出。然而，对于较大规模的工作和重要的更新及新增内容，应遵循以下流程。重要的工作可能包括但不限于

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

对于此类变更，贡献者将

  • 在 GitHub 问题跟踪器中创建一个或多个问题
  • 在 janusgraph-dev 邮件列表中启动一个 DISCUSS 讨论串，供提交者和其他社区成员讨论提议的变更
  • 当提议者认为合适时，将进行 VOTE 表决
  • 需要两个 +1 票才能接受变更

分支

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

分支命名约定

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

拉取请求

希望为 JanusGraph 贡献的用户应该 fork JanusGraph 仓库，然后使用 GitHub 拉取请求流程提交拉取请求。每个拉取请求都必须与一个现有问题相关联。请务必在拉取请求的标题中包含相关的问题编号，完成拉取请求模板清单，并提供运行了哪些测试套件来验证拉取请求的描述。拉取请求的提交消息应清晰地描述所完成的工作。在提交拉取请求之前，应合并中间的进行中的提交。

先评审后提交（RTC）

拉取请求必须在合并之前遵循先评审后提交（RTC）流程进行评审。JanusGraph 项目使用 GitHub 评审流程来评审拉取请求。非提交者也欢迎并鼓励评审拉取请求。他们的评审将是非约束性的，但可以被考虑，并且仍然是非常有价值的社区输入。以下规则适用于投票流程。

  • 批准流程
    • 需要 2 位提交者批准才能合并拉取请求
    • 如果提交者提交了拉取请求，则其隐含地获得该提交者的批准，因此只需 1 位额外的提交者批准
    • 在 1 位提交者批准后，进行为期一周的异议评审期，在此之后，假设达成松散共识
  • 变更请求中出现一个或多个 -1 票将否决该拉取请求，直到解决所指出的问题并撤回 -1 票
  • 没有解释的变更请求将不被视为有效

先提交后评审（CTR）

在提交者认为完整的 RTC 流程没有必要的情况下，可以采用先提交后评审（CTR）流程。启用 CTR 的目的是为了减轻提交者的负担，并最大限度地减少合并微不足道的变更所需的时间。此类变更可能包括

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

任何遵循 CTR 的提交都应在提交评论中注明其为 CTR。希望评审 CTR 的社区成员可以订阅 JanusGraph commits 列表，以便他们能看到新的 CTR。如果另一位提交者回复 -1，则应回滚该提交，并遵循正式的 RTC 流程。

启用自动向后移植

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

拉取请求的合并

当拉取请求获得批准（请参阅先评审后提交（RTC））后，即可合并。可以使用 git 命令手动合并，也可以通过 GitHub UI 合并。

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

手动向后移植

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. 将 JanusGraph 仓库从 GitHub 克隆到本地目录。

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

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

常见问题

Maven 构建导致数十个“[WARNING] 我们有重复的…”错误

在构建或依赖 JanusGraph 时，请务必使用 maven-assembly-plugin。