Docs Maintainers

维护文档与上游同步

准备内容

• 维护者 fork 的项目地址，类似：https://github.com/username/dart.cn
• CFUG 上游文档：git@github.com:cfug/dart.cn.git
• Dart 上游文档：git@github.com:dart-lang/site-www.git

环境配置

安装 Git 之后，执行如下命令：

git clone https://github.com/username/dart.cn
cd dart.cn
git remote add cfug https://github.com/cfug/dart.cn.git
git remote add dart https://github.com/dart-lang/site-www.git
git fetch cfug
git fetch dart
git pull cfug main
git push
git pull dart main

接下来处理冲突的文档，然后执行 push 命令，接着是到页面发起 Pull Request。

远程 module 更新的冲突操作：

git submodule # 查看目标的子模块
git submodule init # 初始化
git submodule update # 这个好似不行
git submodule update --remote # 运行了这个好像才行
git add .
git commit
git push

某次的 log

常见 CI 问题修复

如果是链接检查不通过，可能是因为上游对文档的修改我们没有及时调整，可以根据 CI 的输出直接修改文档。

如果是一些代码跑不通而导致的 CI 错误，一般我们就在本地跑一下测试，看看输出内容里的提醒。

Codespaces 里执行代码测试脚本

1. 安装 Dart
2. 设定 BASE_DIR 和 TOOL_DIR 环境变量

export BASE_DIR=/workspaces/dart.cn
export TOOL_DIR=/workspaces/dart.cn/tools

3. 执行代码测试脚本

sh ./tools/test.sh

4. 打开项目目录下的 tmp 文件夹，查看 log 信息

11/28 sync 里出现了这样的代码测试报错:

Error: /workspaces/dart.cn//src/_articles/libraries/dart-io.md:64 excerpt not found for "misc/lib/articles/io/io_timer_test.dart"
Error: /workspaces/dart.cn//src/_articles/libraries/dart-io.md:100 excerpt not found for "misc/lib/articles/io/io_file_system_test.dart"
Error: /workspaces/dart.cn//src/_articles/libraries/dart-io.md:131 excerpt not found for "misc/lib/articles/io/io_random_access_test.dart"
Error: /workspaces/dart.cn//src/_articles/libraries/dart-io.md:168 excerpt not found for "misc/lib/articles/io/io_stream_test.dart"
Error: /workspaces/dart.cn//src/_articles/libraries/dart-io.md:208 excerpt not found for "misc/lib/articles/io/io_process_test.dart"
Error: /workspaces/dart.cn//src/_articles/libraries/dart-io.md:241 excerpt not found for "misc/lib/articles/io/io_process_transform_test.dart"
Error: /workspaces/dart.cn//src/_articles/libraries/dart-io.md:272 excerpt not found for "misc/lib/articles/io/io_process_stdio_test.dart"
Error: /workspaces/dart.cn//src/_articles/libraries/dart-io.md:303 excerpt not found for "misc/lib/articles/io/io_http_server_test.dart"
Processed 178 Dart/Jade/Markdown files: 0 out of 849 fragments needed updating.

同步文档的时候知道这个 dart-io.md 文档是被删除了，所以我先检查一下这个文件是否没有被删除。

经检查，果然是没有删除，但是印象里 sync 处理 conflict 冲突的时候，有 deleted by 上游的提示，但为什么实际上并没有删除呢？