Monorepo

Monorepo 是一种代码组织方式,将所有有关项目都放在同一个 repo 中。与 Multirepo 相对,Multirepo 中各个项目各自拥有各自的 repo。

据说,Google 所有的代码都维护在一个「repo」里,这也可以理解成「monorepo」。

Why monorepo

在初期开发的时候,基本上就是一个模块开一个 repo 的,基本比较流畅。尤其是我使用了create-react-app这一类的东西,会直接帮你建好一个新的 git repo。之后也是一个 repo 一个 repo 地测试和打包镜像,如果后一个 repo 依赖前一个 repo 提供的服务,也是通过起 Docker 容器的方式满足后一个 repo 的依赖来调试。

整个项目基本完成以后,也就暂时放在那了(即使还有不少已知 Bug)。之后想找个地方记一下有哪些 Bug,当然首先是想到了 GitHub 的 issues 模块,结果一看就傻眼了,很纠结有些 Bug 到底应该提到哪里,如果太散乱也不好管理。这时就种草了 monorepo。

另外其实这个项目目前就我一个人搞,把 repo 搞的到处都是也不方便自己浏览和维护。而且名字类似的一长列 repo 占据了我的 GitHub 首页左边栏,也有碍观瞻。总之,最后就下定决心要把这些 repo 迁移到一个 monorepo 了。

Tomono

tomono 是一个「Multi- To Mono-repository」的迁移工具。这是一个 shell 脚本,只有 100 来行。使用也比较方便,简单来说,你给它一个 repo list,它会自动帮你梳理 git log/branch/tags,合理地将多个 repo 合并成一个 repo。具体的代码和用法可以直接在 GitHub 参考。个人的用法比较粗暴,直接一个文件夹一个 repo 放在根目录下,没有像 lerna 那样再套一层 packages 路径。其实由于这个项目没有 npm 模块需要发布,所以没有必要使用 lerna 等 monorepo 管理工具。

由于 tomono 的过程中需要做git fetch,而我这些 repo 中其中有一个和环境配置有关,放了很多编译产物,比较大,于是先从 list 里去掉了。tomono 很顺利地帮我合并了剩下的 6 个 repo。由于这些 multirepo 我之后不再需要了,因此要不然 delete,要不然 archive 了。但 tomono 自动会在 remote 里添加这些旧的 repo,因此需要手动git remote remove掉。当然,还要把最后那个 repo 手动mv进来。tomono 不会处理你的 LICENCE 和 .gitignore,可以自行拿出来或者合并一波。

After

由于多个 repo 合并成了一个,有些问题之前影响不大,现在也暴露了出来。最典型的就是 GitHub 页面上显示的 Languages 比例直接歪了。本来这个项目应该是一个 Python 和 JavaScript 再加上一些 C 语言的项目,结果因为 C 语言那边放了一个argparse3依赖库,直接就以将近 50% 的比例当选了这个项目的代表语言。此外,那边的编译产物的一堆 html 格式的文档和脚本,也占了一大片山头。

before

这时候就需要在根目录建一个 .gitattributes 文件,对一些不应该计入语言统计的文件设置linguist-vendored=true参数,如下

1
2
argtable3.* linguist-vendored=true
some_repo/some_build/**/* linguist-vendored=true

这样就科学多了。

after

CI/CD

CI/CD 指的是持续集成/部署。一个很 DevOps 的概念。主要是关于代码写完之后一些自动化的事情,例如编译构建镜像,以及测试、发布等。

repo 组织形式的变更,也伴随着 CI/CD 方式的变更。相对语言统计什么的来说,这是个比较大的问题。

本来这个项目的 7 个仓库,其中 5 个是需要 build 出镜像的,其中 2 个对另 1 个编译出的镜像产物有依赖。还有 2 个仓库,一个用来放些部署配置,一个是端到端自动化测试。

之前是在阿里云的镜像中心管理的,为了docker pull速度相对可以接受一些。具体做法是每个 repo 开一个 image,master 分支有变更会触发 latest tag 的 image 构建。显然这在 monorepo 的场景下不再适用。

时过境迁,GitHub 也推出了看起来可用的 GitHub Actions,可以用 yaml 文件自定义 workflow 来做 CI/CD。有了 workflow,其实可以做到更多事情,例如构建完了部署一把,然后跑自动化测试。这在有机器人提 vulnerability 相关的 PR 的时候会非常有用,可以直接在页面上看到依赖版本变更有没有导致测试失败。显然之前 multirepo 的组织方式是没法做的。当然这和我这些仓库的拆分以及没写单元测试有关系。

例如,如下是一个示例的 Docker 镜像构建的 workflow yaml,放在.github/workflows路径下

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
name: Docker Image CI

on:
push:
branches: [ master ]
pull_request:
branches: [ master ]

jobs:

build:

runs-on: ubuntu-latest

steps:
- uses: actions/[email protected]
- name: Build the Docker image
run: docker build . --file Dockerfile --tag my-image-name:$(date +%s)

首先我们需要知道怎样的修改触发怎样的构建。第一步,构建镜像并 push 需要登录 Docker Hub,而为了密码不泄露,可以使用 GitHub 的 Secrets 功能,在里面增加对应的用户名和密码变量,并在 yaml 文件中使用。

对于 monorepo 的情况,我们需要根据哪些文件有改动来决定如何构建。GitHub 官方提供了 workflow 级别的这个 feature,根据有改动的路径,我们决定不做哪些构建、做哪些构建。看起来没什么问题,但在 workflow 级别做这个事情还不够灵活。例如,不能满足构建镜像有依赖的情况。第三方 action dorny/paths-filter 则一定程度上增加了 path 检查的灵活性。它在 steps 级别,利用 filter 和 if 的功能使得一些操作的执行是有条件的。这样结合 steps 的串行执行我们可以处理镜像构建时 A、B 依赖 C 的情况。不过也有个缺点, A 和 B 的构建这样就不能并行了。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
name: Pipeline

on:
push:
branches: [ master ]

jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/[email protected]
- uses: dorny/[email protected]
id: filter
with:
filters: |
A:
- 'packageA/**/*'
B:
- 'packageB/**/*'
C:
- 'packageC/**/*'
- name: login
run: docker login docker.io -u ${{ secrets.HUB_USER }} -p ${{ secrets.HUB_PSWD }}
- name: build C
if: steps.filter.outputs.C == 'true'
run: |
docker build packageC --tag ${{ secrets.HUB_USER }}/imageC:latest
docker push ${{ secrets.HUB_USER }}/imageC:latest
- name: build A
if: steps.filter.outputs.C == 'true' || steps.filter.outputs.A == 'true'
run: |
docker build packageA --tag ${{ secrets.HUB_USER }}/imageA:latest
docker push ${{ secrets.HUB_USER }}/imageA:latest
- name: build B
if: steps.filter.outputs.C == 'true' || steps.filter.outputs.B == 'true'
run: |
docker build packageB --tag ${{ secrets.HUB_USER }}/imageB:latest
docker push ${{ secrets.HUB_USER }}/imageB:latest

自动化测试则需要另一个 workflow。测试用例使用了自动化框架 TestCafe,其官方文档提供了一个 GitHub Action,用法如下。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
name: End-to-End Tests
on:
pull_request:
branches: [ master ]

jobs:
test:
name: Run TestCafe Tests
runs-on: windows-latest
steps:
- name: Check out the repository
uses: actions/[email protected]
- name: Run tests
uses: DevExpress/[email protected]
with:
args: "chrome tests"

当然,在运行测试需要先部署,这部分就比较 trick 了,首先依然是按照上面的方法筛选变更的 path,之后由于部署时在docker-compose.yaml用到的镜像名是写死的,因此 workflow 中的镜像构建也需要使用相同的镜像名。这样可以做到本地构建过时先使用本地的镜像,本地没有时从 Docker Hub 拉取。

Which is best

相比 multirepo,虽然解决了依赖混乱和代码零散等问题,monorepo 也并非完美无缺的。比如导致了 repo 的体积非常大(尤其是有大文件的被合并入 monorepo),而每次构建都需要全都拉取下来,拖慢了构建速度。以及在 CI/CD 时需要一些逻辑处理。

另外,虽说 monorepo 里应该放所有相关项目,但有的时候一些相关项目可以作为外部项目的依赖。这个时候也可以考虑拆出去,是有道理的。比如前文提到的 fetch 不下来的那个 repo,其实也可以给另外一个系统当基础镜像用,所以现在又在考虑是不是还是再拆出去比较好。当然还是需要一些权衡的,例如拆出去了以后 monorepo 里的依赖如何自动更新。

所以,事实上并没有最好的代码组织方式,无论是 multirepo 还是 monorepo,都各有优缺点。要根据具体的场景,决定是单独开一个新的 repo,还是写在已有的 monorepo 里。