注意:以下翻译的准确性尚未经过验证。这是使用 AIP ↗ 从原始英文文本进行的机器翻译。

分支和发布流程

本文档的目的是概述分支管理的推荐最佳实践以及通过代码仓库中的项目管理的数据管道发布流程。

高层次目标是设计一个流程,在新数据特性/数据质量修复的快速迭代和具有稳定且符合流程的变更管理流程之间取得平衡。

发布范围

在我们深入探讨发布管理流程的内部细节之前,我们需要更好地定义我们发布的“产品”到底是什么?为了我们的目的,我们将定义产品作为概念单元发布的一组资产

推荐项目结构为我们在Foundry中搭建管道的参考,我们看到管道是由多种类型的多个项目定义的——数据源、变换、Ontology和工作流。然而,在大多数情况下,我们不会将每个项目单独管理为一个产品,而是每个项目将其资源子集定义为以下产品类型之一:

  • Ontology产品:此产品是由数据源、管道和Ontology项目创建的输出数据集的集合。
  • 应用案例产品:每个应用案例项目表示一个独立的应用案例。每个应用案例都被定义为一个产品。

pipeline-overview

我们在这里给产品的定义可以涵盖在多个仓库中管理的代码和其他Foundry资源。

产品分支管理

以下部分涉及我们希望部署的分支策略,以管理每个产品的发布。了解有关分支的一般信息以及代码仓库和数据集之间分支如何工作的更多信息。

分支命名

强烈建议在产品内的所有仓库中使用相同的分支名称。这将确保下游分支从正确的上游分支读取。

我们推荐的通用分支策略基于一种名为GitFlow ↗的常见实践,但进行了某些修改。主要的更改是建议跳过release分支。由于在Foundry中部署工件的方式,我们可以在测试后直接将更改从dev合并到master

常见分支

master - 这是生产分支。因此,它是一个受保护的分支,只有发布经理角色可以批准将PR合并到此分支中。假定master分支是使用生产数据进行来源的。

dev - dev(即开发)分支是从master分支派生的暂存分支。当您希望使用测试数据测试完整功能时,这个分支最为相关。dev分支可以从master来源(通过回退分支自动完成)或从UAT数据源来源。

feature-[X] - 功能分支是开发和测试特定功能的地方。此分支是从dev分支派生的。这是一个短期分支,意味着一旦分支合并到master后可以删除。由于分支是从dev派生的,它将与dev分支具有相同的数据来源。注意,只要回退分支未重新配置,并且功能分支上不存在输入数据集,这一点始终成立。

basic-branching

其他特殊分支

major-release-[X] - 由于源系统架构的变化(在特定节奏下发生)而集成所有必要更改的特殊分支。

hot-fix-[X] - 用于修复在生产中发现的问题的特殊分支,而代码库已移动到新版本。由于假定devmaster是同步的(除非有正在积极测试的功能),因此不太可能需要这样的分支。

分支管理工作流程

如上所述,一些分支是永久性的,而其他分支是短期的。以下部分描述了分支之间的推荐工作流程。

advanced-branching

  • t0,创建masterdev分支。

  • t1,从dev创建feature x分支。

  • t2,从dev创建feature y分支。

  • t3,将feature x合并到dev

  • t4,将dev合并到master,并删除feature x分支。

  • t5,将dev合并到feature y以获取dev的最新状态。

  • t6,如前所述,将feature y合并到dev,然后从dev合并到master

除了开发和发布到devmaster的功能外,还会开发一个长期存在的主要版本分支,例如major-release-[X]

建议将dev不断合并到major-release-[X],以便最新功能保持同步。我们建议尽可能保持Ontology架构的稳定,并通过数据源和变换项目中的变换隐藏后端架构更改。

仓库升级

_仓库升级_是定期提示更新代码仓库中的配置文件。这些更新应用修复或提升语言包依赖项的版本,最佳实践是保持这些推荐升级的最新状态。

upgrade button

注意,如果您错过了点击提示中的“升级”按钮,该按钮也可以在右上角“...”选项菜单下的任何分支中使用:

upgrade button

升级过程应与功能开发周期相同。这意味着:

  1. master应通过dev进行升级。

  2. 当提示升级dev时,将创建一个自动化的功能分支。您可以在CI检查完成后通过在此分支上运行构建来测试配置更改。在确认升级后变换仍然执行后,将配置更改合并到dev中。一旦dev升级完成,应使用PR将这些更改推送到master

  3. 要升级所有打开的功能分支,将dev合并回每个分支,以包含这些配置升级。

维护窗口

从创意到生产的快速迭代循环在开发实践中很常见,并且对于依赖最终用户反馈来确定下一个迭代循环的项目的成功至关重要。为了支持这样的流程,我们建议建立一个预定义的维护窗口。

例如,一旦所有功能PR合并,所有数据集将在dev分支上构建,以便在周三和周五验证结果。在这些日子里,只有在验证过程中发现的问题的修复被合并到dev中,直到dev最终在周四和周一,即“发布日”合并到master

upgrade-windows

建议与所有相关方达成一致,以确保他们在这些日子里投入足够的时间推动新功能向前发展。

功能测试和最终用户验证

一旦功能开发完成,测试和验证功能结果的正确性及其对任何依赖资源的影响至关重要。在代码仓库中,我们认为输出数据集是应该测试的功能结果。

基于我们上面定义的分支结构,当我们构建输出数据集时,它将使用来自功能分支的输入数据集的数据,或者通过回退逻辑从源分支读取数据,即简化版本中的master和其他版本中的dev

开发人员级别的测试可以使用数据集健康检查、依赖测试数据集或手动使用工具如Contour进行。

测试方法

强烈不建议通过预览或SQL助手进行测试。预览助手在执行代码时仅使用数据样本,这可能不会揭示所有情况——尤其是在涉及一个或多个合并操作的代码中。SQL助手测试代码的正确性,但不测试构建的输出,在某些情况下可能会有所不同。

在功能开发完成后,新功能代码需要在合并到dev分支之前进行审核,并且功能结果需要由最终用户验证其正确性和完整性。

我们建议使用拉取请求审查和Foundry问题的组合来进行审核和验证,如下图所示。

pull-request

  1. 开发人员从他的功能分支创建一个到dev分支的拉取请求,并添加实现评论。

  2. 开发负责人审查PR,与开发人员合作进行必要的更改,最终将PR合并到dev

在拉取请求审查期间,请确保检查任何受影响数据集的架构更改。架构应被视为您的数据API,因此对列名或列类型的任何更改都被视为对任何消费者的“破坏性”更改。尽可能通过创建新列而不是删除或修改旧列来限制破坏,同时宣布旧列的弃用和数据消费者(通过数据连接识别)的更新指示。在下一个主要版本中,可以删除在前一个主要版本中弃用的列。

要审查拉取请求中的架构更改,请使用Affected Datasets选项卡中的架构差异视图。

  1. 开发负责人在dev分支上运行构建以创建功能输出数据集。
  2. 开发人员在输出数据集上创建一个Foundry问题,记录任何测试和验证请求,并将问题指派给相关的最终用户进行验证。
  3. 最终用户收到问题,具有完整的上下文和相关数据集和分支的视图进行测试。他们与开发人员合作进行必要的更改,直到问题解决并标记为准备合并。然后将问题指派给发布经理。
  4. 发布经理关闭问题并将dev合并到master
  5. 发布经理删除功能分支。

上述工作流程允许各方之间进行相对快速的协作循环,而不会丢失上下文。已关闭的问题保留在平台上,可以作为变更管理流程的审计记录。

Foundry问题功能审查工作流程

以下是团队如何使用Foundry问题来跟踪其他利益相关者的审查请求、围绕新功能进行讨论以及控制和记录将代码合并到master的过程的示例,以便所有相关方保持知情和最新状态。请将其视为方向性建议,而不是强制性的,并根据需要适应现有的操作和技术流程。

示例工作流程

首次开发人员创建功能审查请求问题时,该问题的状态为Feature Review: Request Review。该问题可以附加到数据集或特定列上,如果功能是特定的。

与最终用户的协作通过评论部分进行,并通过在Request ChangeReady to Merge之间更改状态以及更改问题的指派人进行。

问题是存储功能审查工作流程的好地方,因为最终用户还可以记录其验证过程(用于审计目的)并附加到其他资产的链接。

下图显示了如何在构建输出数据集上创建问题。

issue-review

  1. 在Foundry Explorer中,选择输出数据集。

  2. 通过点击报告问题报告整个数据集的问题。

  3. 如果功能与特定列有关,您可以使用列级报告问题以为审查员提供您所做更改的更好上下文。

  4. 根据表单提示完成问题字段。

  5. 问题创建后,请确保将标签更改为Feature Review: Request Review。如果您没有这些标签,请联系您的Palantir代表寻求帮助。

issue-review3

随着审查过程的进行,包括所有状态更改和验证证据的协作线程将存储在问题中。

issue-review4