Newshot

使用 Maiao 的堆叠式 diff

Translation(model translation, not the source's own text)
stacked-diffs-with-maiao.jpg
stacked-diffs-with-maiao.jpg

在路上?听听本文的 ai 朗读版。

看不懂?了解关于 ai 朗读的更多信息。

我使用 Maiao 的社区分支已经有一段时间了,它非常出色。对于任何偏好使用堆叠式 diff 工作流、但又需要与 GitHub 这类更传统的代码托管平台打交道的人,不妨试用一下 Maiao。几乎在所有情况下,它都能做出正确的处理。它至少把我对 GitHub 的挫败感减半,甚至更多。

对于那一小群对堆叠式 diff 感到兴奋的读者来说,这大概已经足够作为推荐理由了。对于其他人,我们稍微往回退一步。

以拉取请求作为变更单位

在传统代码托管平台上11 比如 GitHub、Codeberg、GitLab、BitBucket 等。,pre-commit22 之所以叫 pre-commit,是因为这种评审发生在代码被合并(“提交”)到上游分支之前,与之相对的是例如审计,那是一种 post-commit 评审。代码评审发生在拉取请求(有时称为合并请求)上,每个拉取请求都从一个 git 分支创建。

刚接触 git 的用户可以把一个分支理解为实现一个小目标的一次开发工作。只要分支顶端还不代表目标状态,他们就会不断往该分支添加提交。最后,当一切看起来都没问题、变更也获得批准时,他们执行一次显式合并。这意味着他们在上游分支上创建一个合并提交,同时引用旧的上游和他們所工作的分支。

这让初学者能够以更小的增量工作,而不必处理重写 git 历史的复杂细节33 有时初学者会被要求改为执行 squash merge,这通常意味着托管平台在上游分支上创建一个单独的普通提交,只引用旧的上游,并包含开发分支顶端所隐含的全部变更。虽然听起来像是重写了历史,其实并不是——旧的开发分支仍然和之前完全一样。区别在于,它所隐含的变更被复制到了上游分支,而没有引用开发分支。;这种工作流降低了使用 git 与他人协作的门槛,这很好。

这也意味着传统托管平台上的评审界面不必处理重写 git 历史的复杂细节。因此,评审界面通常只显示仍在开发分支上的提交之间的差异,而不显示“同一个”提交的两个版本之间发生了什么变化——当其中一个版本已不在该分支上时。

更具体地说,下面是使用这种工作流的一个项目历史图的一部分示例。44 提交并非按时间顺序显示。我在不改变图结构的前提下(在可能的地方)重新排列了它们,让图读起来更清晰。


        ▲ (upstream)
│
│   ▲ (input-validation)
│   │
│   │   ▲ (priv-cache)
│   │   │
│   ●   │       Tighten input validation
│   │   │
│   │   ●       Rename cache variables
│   │   │
│   │   ●       Cache user permissions
├───╯   │
●◀──╮   │   Merge flaky-test-fix (PR #835)
│   ├───╯
│   ●           Fix timezone offset instead
│   │
│   ●           Disable login test
│   │
●◀──┼───╮   Merge log-migration (PR #834)
├───╯   │
●◀──╮   │   Merge avatar-upload (PR #833)
│   │   │
│   ●   │       Fix typo in readme
│   │   │
│   ●   │       Clean up unused imports
│   │   │
│   ●   │       Add avatar upload
├───╯   │
●◀──╮   │   Merge parser-null-check (PR #832)
│   │   │
      

我们可以看到总共 12 个提交。其中四个是上游分支上的合并提交,而这四个合并提交中有两个对应着我们可以看到工作内容的分支(avatar-upload 和 flaky-test-fix)。我们可以看到这两个分支分别有三个和两个实际工作的提交。

文章标题:使用 Maiao 的堆叠式 diff

正文: 然后还有两个分支(input-validation 和 priv-cache)仍未关闭(未与上游合并)。其中一个(priv-cache)包含两次提交的工作,并且它不是基于上游分支,而是基于较早的某个分支(flaky-test-fix)在合并之前的最终结果。

以提交为变更单位

我们不必那样使用 git。我们可以改为只保留一个开发分支。我给它起个通用的名字,比如 dev。在该分支上,每个目标状态由一个提交表示。因此,不再是多个分支(每个目标一个)上各带多个提交(通向实现的步骤),而只是一个分支(一个通用开发分支)上带多个提交(每个目标一个)。

修补已有的提交

在这种工作流下,如果我们发现某个提交不能代表该变更的目标状态,我们就编辑那个提交55 严格来说,git 不允许用户编辑提交。底层发生的是该提交被替换为一个新提交。但借助提交信息中的 change id,我们仍然可以辨别它们代表同一个原子变更。,而不是追加更多提交。66 如果我们需要回退到旧提交怎么办?幸运的是,git 会维护一个包含旧提交的 reflog。这些提交会一直保留,直到 git 决定对悬空引用进行垃圾回收。这样,每个进行中的原子变更都恰好在一个提交中实现,且全部位于一个开发分支上。dev 分支可能有很多提交,但它们代表不同的原子变更,而不是通向某一个目标状态的进展。

这种工作方式也被称为制作堆叠式 diff,我发现它比为每个原子变更单独开一个分支更容易、更快捷。许多经验丰富的软件工程师也认同。77 我应该说,我不同意 Gergely Orosz 的说法,即不可能创建一个依赖于较早的、尚未合并的拉取请求中变更的拉取请求。这是可能的(在大多数 forge 中甚至很容易),但要同时应付分支和合并目标需要大量额外工作。从根本上说,拉取请求与堆叠式 diff 之间并不存在深层次的不兼容。人们更喜欢专为堆叠式 diff 打造的工具,原因在于使用这些工具时,满足 git 要求所需的繁琐手续更少。

合并堆叠式 diff

合并堆叠式 diff 的理想方式是将它们复制到上游分支上,可以通过 cherry-pick,或者在 forge UI 中选择 rebase and fast-forward 合并类型。这样产生的上游分支历史会非常清晰地按发生顺序列出每个原子变更,而不包含过程中的错误步骤和失误。

初学者可能认为这不诚实。重点不在于掩盖自己的错误,而在于呈现一段其他开发者能在三年后读懂并跟随的历史,那时他们想了解项目是如何变成当前状态的。就这个目的而言,只有最终进入上游分支的内容才重要。

重新审视历史图

上面那个示例历史图在堆叠式 diff 型工作流下会更像这样:


        ▲ (upstream)
│
│    ▲ (dev)
│    │
│    ●       Tighten input validation
│    │
│    ●       Cache user permissions
│    │
●◁┄┄┄◌   Fix timezone offset in login test (PR #835)
├───▶┤
●    │   Migrate to structured logging (PR #834)
│    │
●◁┄┄┄◌   Allow users to upload avatars (PR #833)
├───▶┤
●    │   Check for null in order parser (PR #832)
│    │
      

写成 {{NAME_ab12cd34}} 这样的值是真实值的占位符。在回复和工具调用中都要完全按原样使用它们:它们会在任何内容运行之前被填入真实值。不要要求验证它们,也不要用示例替换它们。

文章标题:使用 Maiao 的堆叠式 diff

正文: 上游分支上的两个提交(空值检查和时区偏移)来自其他人。在这两个提交之间,我们把长期存活的 dev 分支更新为最新上游的状态,然后把已完成的 avatar 提交复制到上游。稍后修复不稳定测试时也经历了同样的过程。我们在同一个 dev 分支中同时处理用户权限缓存和输入验证,而不是新建两个独立的分支。等这些提交获得批准并通过 ci 后,就会像之前的提交一样被复制到上游分支。

所有这些提交都需要修订,次数与上一张图中一样多,只不过我们是通过替换提交来修订,而不是不断追加新提交。

这就是人们所说的“一个原子变更就是一个提交,一个提交就是一个原子变更”。

堆叠式 diff 的缺点

堆叠式 diff 工作流有一个不幸的后果:当所有提交都在一个分支上时,它们看起来会按照在分支上的顺序相互依赖,即使它们实际上包含的是彼此独立的变更。当所有提交都在一个分支上时,无法看出哪些提交是独立的,除非 (a) 阅读代码,并且 (b) 尝试 cherry-pick 其中一个变更。88 两者都需要,因为尽管变更相互独立,cherry-pick 或 rebase 在 git 中也可能发生冲突(当它们在源代码中恰好位置相近时);而相互依赖的变更,在 git 看来也可能干净地 cherry-pick,即使它会导致代码出错(当变更位于代码中的不同位置,但其中一个变更假设另一个已经发生时)。

如果向我们自己记录“我们有两个相互独立的并行工作流”这一点很重要,我们可以使用两个本地通用开发分支(我把自己用的叫 dev,以及很有想象力地叫 dev2)。每个分支仍然被当作一堆 diff,也就是说每个提交代表一个原子变更,但现在非常清楚的是,两个分支之间的提交不可能相互依赖。

堆叠式 diff 在 pull request 场景下很烦人

到这里,你大概能猜到为什么传统代码托管平台的 pull request 工作流很烦人了。pull request 假设每个原子变更都有一个分支,但在堆叠式 diff 中,我们只有一个分支,而我们希望每个提交都变成一个独立的 pull request,并基于前一个提交。

我以前处理这件事的方式,恰恰是你意想不到的那种繁琐:

  • 我为每个提交手动创建一个分支。
  • 我把所有这些分支推送上去。
  • 我打开 GitHub 的 web ui,为每个分支创建一个 pull request,并小心地把每个 pull request 的合并目标设置成前一个分支。
  • 合并时,我又必须小心地按正确顺序合并。

这是很大的工作量。99 总工作量仍然比每个原子变更一个分支要少,但也只是勉强少一点!Maiao 解决了这个问题。

Maiao 是自动化的极致

如今,当我感觉可以为自己的提交创建 pull request 时,我会触发 git review 命令。Maiao 随后会自动完成我以前手动做的所有事情,而且做得比我更好。它会拉取最新的上游,把当前分支 rebase 到上游,为每个提交创建一次性分支,推送这些分支,通过 GitHub api 为每个一次性分支打开一个合并目标正确的 pull request,并把它们变成一个原生的 GitHub pull request 栈,这意味着它们会按正确顺序合并,并且可以在准备好时一次性全部合并。

文章标题:使用 Maiao 进行堆叠式 diff

正文: 如果代码审查或 CI 构建发现了我需要修改的地方,我会像以往一样:替换需要修改的那个提交。然后再次运行 git review,Maiao 就会自动做正确的事:它会再次变基到最新的上游,把一次性分支移动到新的提交上,强制推送它们,根据提交信息的变更更新 pull request 描述,更新任何已发生变化的合并目标,等等。

Maiao 就是一个命令(git review)。运行时,它让 GitHub pull request 栈与我们的本地开发分支保持一致。它只做这些,也只需要做这些。

处理多个分支和未完成的工作

在存在多个本地开发分支的情况下(因为工作是独立且并行的),git review 可以独立地在其中任意一个或两个分支上运行,Maiao 会如你所愿地为每个分支创建一个栈。

还要注意,Maiao 不必为整个开发分支创建 pull request。也许我们还在处理最上面的几个提交。这时我们可以创建一个临时分支,指向我们确实想要 pull request 的最上面的提交。当我们检出该分支并运行 git review 时,Maiao 只会为该分支中包含的提交创建 pull request。然后当我们完成那些顶部提交后,可以在开发分支上运行 git review,Maiao 会理解最上面的提交建立在已经有 pull request 的提交之上,于是它会把新提交的新 pull request 堆叠在之前提交已有的 pull request 之上。

以上所有这些说明,Maiao 并不关心你在本地如何分支。一个不错的心智模型是:它为 head 与 master 分支之间的每个提交创建并更新 pull request,使 forge 上的栈与本地提交保持一致。仅此而已。

而且它棒极了。

The translation is machine-generated and individual terms may be off. Nothing is rewritten or cut; the original is authoritative.

Published by Lobsters
This site only summarises and aggregates; copyright stays with the original author. Headlines and summaries follow the source — where they differ, the original wins.
Read the original ↗