在单个存储库中管理多个 Dart 包。
安装
> dart pub global activate mono_repo
运行
> dart pub global run mono_repo
或者,在[设置好 PATH] 后:
> mono_repo
打印以下帮助信息:
在一个源代码存储库中管理多个包。
用法:mono_repo <命令> [参数]
全局选项:
-h, --help 打印此使用信息。
--version 打印 mono_repo 的版本。
--[no-]recursive 是否递归遍历子目录寻找包。
(默认开启)
--verbose 出错时显示完整堆栈跟踪。(用于调试)
可用命令:
check 检查存储库的状态。
dart 在所有包中运行带提供参数的 `dart` 命令。
generate 为子包生成 CI 配置。
list 列出为 mono_repo 配置的所有包。
presubmit 在本地运行 CI 预提交检查。
pub 在所有包中运行带提供参数的 `pub` 命令。
readme 为所有配置的 mono_repo 包生成 markdown 表格。
运行 "mono_repo help <命令>" 获取有关命令的更多信息。
配置
存储库级配置
首先,你应该在存储库根目录创建一个 mono_repo.yaml
文件。
这控制了整个存储库范围的配置。
你可能想要配置的一个选项是为哪些 CI 提供商生成配置。可以通过添加相应的条目来配置 github
。
你可能还想启用 self_validate
选项,它会添加一个作业以确保你的配置是最新的。
因此,一个示例配置可能如下所示:
# 启用 GitHub actions - https://docs.github.com/actions
# 如果没有配置,你可以将值设置为 `true` 或直接留空。
github:
# 指定 `on` 键来配置触发事件。
# 参见 https://docs.github.com/actions/reference/workflow-syntax-for-github-actions#on
# 默认值为
# on:
# push:
# branches:
# - main
# - master
# pull_request:
# 只设置 `cron` 是一种快捷方式,可以保留 `push` 和 `pull_request` 的默认值,
# 同时添加一个 `schedule` 条目。
# `on` 和 `cron` 不能同时设置。
cron: '0 0 * * 0' # "每周日 00:00 (UTC)。"
# 指定所有作业可访问的附加环境变量
env:
FOO: BAR
# 你可以将阶段分组到单独的工作流程中
#
# 这里省略的任何阶段都会被放入名为 `dart.yml` 的默认工作流程中。
workflows:
# 这里的键是文件名 - .github/workflows/lint.yml
lint:
# 这会填充工作流程中的 `name`
name: Dart Lint CI
# 这些是填充到工作流程文件中的阶段
stages:
- analyze
# 你可以在这里添加自定义 github actions 配置,在所有其他作业完成后运行。
# 这接受正常的 github 作业配置,除了 `needs` 配置会为你填充,并且不允许你传递它。
on_completion:
# 示例作业,在失败时向存储在 github secret 中的 web hook url 发送带有失败运行链接的 json 负载。
- name: "通知失败"
runs-on: ubuntu-latest
# 默认情况下,只有所有依赖作业成功时才会运行此作业,
# 但我们希望在失败的情况下运行。
if: failure()
steps:
- run: >
curl -H "Content-Type: application/json" -X POST -d \
"{'text':'构建失败!${GITHUB_SERVER_URL}/${GITHUB_REPOSITORY}/actions/runs/${GITHUB_RUN_ID}'}" \
"${CHAT_WEBHOOK_URL}"
env:
CHAT_WEBHOOK_URL: ${{ secrets.CHAT_WEBHOOK_URL }}
# 你也可以在这里自定义阶段顺序,并使某些阶段成为条件性的,
# 这对所有 CI 提供商都支持。`if` 条件应使用适合正在配置的提供商的语法。
stages:
- name: cron
# 仅为计划的 cron 作业运行此阶段
if: github.event_name == 'schedule'
# 添加一个运行 `mono_repo generate --validate` 的作业,以检查一切是否最新。
# 你可以将值指定为 `true`,或者给出你希望此作业运行的 `stage`。
self_validate: analyze
# 使用此键合并包之间的阶段,以创建更少的作业
merge_stages:
- analyze
# 使用 `test_with_coverage` 时,此设置配置上传结果的服务。
# 注意:你可以同时配置两个选项,但这种情况比较少见。
# 注意:你可以将此键配置为无值,仅在本地生成文件。
# 这可能是为了启用其他自定义处理。
coverage_service:
# https://coveralls.io/ - 默认选项
- coveralls
# https://codecov.io/ – 另一个选项
# 注意:必须在 GitHub actions secrets 中设置 `CODECOV_TOKEN`
- codecov
添加包配置
要配置包含的包目录,必须包含一个 mono_pkg.yaml
文件(以及常规的 pubspec.yaml
文件)。
你可以使用一个空的 mono_pkg.yaml
文件来启用 check
和 pub
命令。
要启用 generate
和 presubmit
,你必须在 mono_pkg.yaml
中填写有关如何运行测试的详细信息。
生成 .github/dependabot.yml
通过在 mono_repo.yaml
配置中添加
github:
dependabot: {}
mono_repo 将生成一个 .github/dependabot.yml
文件,使用默认配置更新所有包。
任何进一步的配置都可以放入该映射中,并将与包的更新合并。例如:
github:
dependabot:
updates:
- package-ecosystem: "github-actions"
directory: "/"
schedule:
interval: "monthly"
mono_pkg.yaml
示例
# 每个条目必须与至少一个 SDK 版本关联 - 对应于
# Dart SDK 版本或 Flutter 框架版本,取决于包的类型。
# 可以在顶层指定为单个值或数组。
# 或者,你可以在每个任务中指定 SDK 版本。
sdk:
- dev
# 特定的 `pubspec` 用于测试 pubspec.yaml 中定义的最低 SDK 版本
# 这仅支持 Dart 包(不支持 Flutter)。
- pubspec
stages:
# 在 `analyze` 阶段下注册两个任务。
- analyze:
- analyze
- format
- unit_test:
- test
# 计划任务阶段示例,仅在计划作业时运行(这里我们运行
# 多个操作系统配置以进行额外验证作为示例)。
#
# 请参阅上面的 `mono_repo.yaml` 示例,了解此阶段的特殊配置。
- cron:
- test:
os:
- linux
- windows
在根目录下运行 mono_repo generate
会生成两个或更多文件:tool/ci.sh
和每个配置的 CI 提供程序的配置文件。
查看这些仓库以了解 mono_repo
的使用示例:
- https://github.com/dart-lang/build
- https://github.com/dart-lang/pub-dev
- https://github.com/dart-lang/shelf
- https://github.com/dart-lang/source_gen
- https://github.com/dart-lang/test
- https://github.com/dart-lang/webdev
- https://github.com/google/json_serializable.dart
Mono_repo 和 Dependabot
历史上,package:mono_repo 和 Dependabot 无法一起使用 - 它们都想维护你的 GitHub 工作流文件。我们已经采用 mono_repo,使你现在可以在仓库中同时使用它和 Dependabot。
在生成工作流配置(mono_repo generate
)时,mono_repo 会将其当前默认的操作版本写入工作流文件。但是,如果它发现仓库有 Dependabot 配置 - 在仓库中有一个名为 .github/dependabot.yaml
的文件 - mono_repo 将解析工作流文件,读取当前的操作版本,并在重新生成文件时使用这些版本。这让 mono_repo 管理文件的整体结构,同时允许 Dependabot 独立地根据需要推进各种操作版本。