测试任务

参与 R2CN 开源实习计划之前，学生需要完成一个测试任务，以便证明已经具备了基本 Rust 编程语言能力和熟练掌握 Git 命令。

任务项目

Mega 项目是使用 Rust 编程语言开发的兼容 Git 的 Monorepo 引擎，在这个项目中有一个模块 libra 是用 Rust 编程语言实现的 Git 命令。 libra 目前只实现了部分 Git 子命令，并且没有完成 Git 子命令的所有参数。

$ libra --help
Simulates git commands

Usage: libra <COMMAND>

Commands:
  init     Initialize a new repository
  clone    Clone a repository into a new directory
  add      Add file contents to the index
  rm       Remove files from the working tree and from the index
  restore  Restore working tree files
  status   Show the working tree status
  log      Show commit logs
  diff    Show changes between commits, commit and working tree, etc
  branch   List, create, or delete branches
  commit   Record changes to the repository
  switch   Switch branches
  merge    Merge changes
  push     Update remote refs along with associated objects
  fetch    Download objects and refs from another repository
  pull     Fetch from and integrate with another repository or a local branch
  remote   Manage set of tracked repositories
  help     Print this message or the help of the given subcommand(s)

Options:
  -h, --help     Print help
  -V, --version  Print version

任务要求

测试任务需要学生自己设计，主要包括以下四种类型，完成其中任何一个任务即可：

测试任务类型:

  1. 通过 libra 和 Git 对比，找到缺失的特性并完成，完善 libra 的功能，通过测试任务的标准是实现 1 个以上的新功能；
  2. 增加 libra 测试用例，提升 libra 质量，通过测试任务的标准新增 5 个以上的测试用例；
  3. 开源社区存在很多 Git 增强功能的程序，分析这些程序的功能，为 libra 增加新的命令和功能， 通过测试任务的标准实现 1 个以上的新功能；
  4. 可自行设计 libra 特性， 为 libra 增加新的命令和功能，或者测试出一个 libra 的 Bug ，修复 Bug 也可以作为测试任务， 通过测试任务的标准实现 1 个新功能或者修复 1 个 Bug ；
  5. Buck2 是 Meta 使用 Rust 开发的大型构建系统，构建的过程中需要编写 BUCK 文件。目前 Rust 三方库 crate 都没有对应的 BUCK 文件，所以为 crates.io 中的 Crate 编写 BUCK 文件并且提交到 buck2-rust-third-party 中亦可作为测试任务，通过测试任务的标准编写 5 个以上的 BUCK 文件或者修复 1 个以上 buck2-rust-third-party 中 BUCK 文件错误；

1. libra 功能补全

测试任务是对比 Git 的命令及参数，为 libra 项目补全缺失的 Git 命令及参数。

如，libra 的 init 命令不支持任何参数,

libra init -h
Initialize a new repository

Usage: libra init

Options:
  -h, --help  Print help

而 Git 的 init 命令支持 --bare 等多个参数,

git init -h
usage: git init [-q | --quiet] [--bare] [--template=<template-directory>]
                [--separate-git-dir <git-dir>] [--object-format=<format>]
                [-b <branch-name> | --initial-branch=<branch-name>]
                [--shared[=<permissions>]] [<directory>]

    --template <template-directory>
                          directory from which templates will be used
    --bare                create a bare repository
    --shared[=<permissions>]
                          specify that the git repository is to be shared amongst several users
    -q, --quiet           be quiet
    --separate-git-dir <gitdir>
                          separate git dir from working tree
    -b, --initial-branch <name>
                          override the name of the initial branch
    --object-format <hash>
                          specify the hash algorithm to use

可以选择为 libra 实现一个 init 的参数（如 --bare）作为测试任务。

注意:

目前 --bare 参数已被实现， 实现逻辑是按照 libra 内部结构实现 bare 模式， 同 Git 的结构不同。可以把两种 bare 做一个转换的功能，同样可以作为测试任务，参与的同学可以自由发挥设计功能，都可以作为测试任务。

2. libra 测试用例补充

libra 的测试用例目前欠缺很多，可以为 libra 添加或改进测试用例作为测试任务。

提示:

  1. 如果使用测试用例作为 r2cn 的测试任务，需要至少添加或修改 3 个以上的测试用例；
  2. 需要在测试任务的 Issue 中分析当前测试用例的问题，如测试覆盖的条件不完整、测试用例的覆盖率不够等，不能添加无效的测试用例；

3. 增加新的命令和功能

当前社区的开源项目中有很多 Git 增强功能的程序，如 Conventional Commits 是一个 Commit Message 编写的规范，可以为 libra 的 Commit 命令添加一个 conventional 参数，使用 AI 生成符合规范的 Commit Message 。

提示:

  1. 在 GitHub 上搜索 Git 相关的开源仓库，找到这样的项目，分析其功能，为 libra 添加新的命令和功能；
  2. 需要在测试任务的 Issue 的描述中介绍参照项目，便于分析计划的功能是否合理，粒度是否适合作为测试任务；

4. 自行设计新功能或修复 Bug

当然也可以根据使用 Git 的经验，自行设计新的功能。请充分发挥自己的想象力，Mega 项目不会拒绝任何有创意的功能；或者测试出一个 libra 的 Bug ，修复 Bug 也可以作为测试任务。

5. 为 Crate 编写 BUCK 文件

Buck2 是 Meta 使用 Rust 开发的大型构建系统，构建的过程中需要编写 BUCK 文件。目前 Rust 三方库 crate 都没有对应的 BUCK 文件，所以为 crates.io 中的 Crate 编写 BUCK 文件并且提交到 buck2-rust-third-party 中亦可作为测试任务。

crate 文件下载地址的模板是 https://static.crates.io/crates/{crate}/{crate}-{version}.crate ， 以 cfg-if 为例 1.0.0 ， 下载地址为 https://static.crates.io/crates/cfg-if/cfg-if-1.0.0.crate ， 使用 wget 下载解压的参考命令为：

cd buck2-rust-third-party/third-party/rust/crates
mkdir cfg-if
cd cfg-if
wget https://static.crates.io/crates/cfg-if/cfg-if-1.0.0.crate
tar -xvf cfg-if-1.0.0.crate
rm cfg-if-1.0.0.crate
mv cfg-if-1.0.0 1.0.0

提交代码注意事项:

  1. 组织目录的标准为 /third-party/rust/crates/{crate}/{version} ， 如 cfg-if 的版本 1.0.0 ， 下载地址为 third-party/rust/crates/{crate}/{version} ， 如 cfg-if 的版本 1.0.0 ， 下载地址为 URL_ADDRESS.crates.io/crates/cfg-if/cfg-if-1.0.0.crate;
  2. 有些 crate 目录包含了 GitHub 的工作流目录 .github 或者一些 IDE 的配置目录如 .idea， 需要在提交时删掉这些目录；
  3. 在项目根目录的 BUCK 的 deps 中添加提交的项目和说明，如：
  # anstyle
  # Example: `buck2 run //third-party/rust/crates/anstyle/1.0.10:dump-style`
  "//third-party/rust/crates/anstyle/1.0.10:anstyle",
  "//third-party/rust/crates/anstyle/1.0.10:dump-style",

6. 联系方式

如果对自行设计新功能，或对测试任务有疑问，可以和 @genedna 联系，如需讨论请发送邮件到 eli@patch.sh ，也可在 论坛 或 R2CN Discord 的 #pretask 频道发起讨论。

测试任务过程

1

第一步：创建测试任务 Issue

  1. 使用 pre-task 的标签过滤 open 和 closed 的 Issue，查看是否有已经有实现和计划实现的测试任务和自己的想法相同: is:issue state:closed label:pre-task 和 is:issue state:open label:pre-task；

也可以在 Mega 的 r2cn 项目中查看已经完成的和正在进行的任务；

  1. 在 Mega 项目中使用 pre-task 测试任务模板创建一个 Issue；
  1. 在 Issue 的标题中简要描述测试任务要实现的功能，在 Description 中对测试任务进行具体描述、包括实现方案。

以下是一个测试任务的参考描述：

[libra] 为 init 命令添加 --bare 参数，代码仓库初始化时使用 bare 模式

[任务描述]
为 init 命令添加 --bare 参数。Git 的 bare 模式（裸仓库）是指不包含工作区
（working directory）的 Git 仓库。 它只包含 Git 内部的版本控制数据
（即 .git 目录的内容），但不会有实际的文件可供修改。

bare 模式的特点：
1. 没有工作区：无法直接修改或提交文件。
2. 只存储 Git 版本库数据：主要用于远程仓库，不用于开发。
3. 不能直接 checkout 代码，但可以用于 push 和 fetch。

libra 的 .libra 目录和 .git 目录的结构不同，本任务参照 Git 的
bare 模式实现 libra 的 bare 模式, 不包含 `.libra` 和 `.git` 转换。

[实现方案]
1. 参考 libra 其他子命令的方式，给 init 命令添加 InitArgs 结构体用于表示
init 命令的参数（在结构体中添加 bool 类型变量 bare 来表示 --bare 参数），
通过 Parser 库解析命令行参数。
2. 根据 bare 值来确定 init 命令是初始化普通仓库还是 bare 仓库，两种仓库的
初始化路径不同。
3. 改变 init 函数中判断仓库已存在的代码逻辑 - 这里参考了 Git 中 setup.c
中的 is_reinit 函数, 通过判断 description 等文件是否存在来确定 libra
仓库是否已经初始化。
4. 为修改后的代码编写测试样例，通过判断目录下是否存在 description、
libra.db 和 info/exclude 目录来判断是否初始化成功。
2

第二步：同 Maintainer 讨论实现方案

  1. 在 Issue 的 Comment 中和 Mega 项目的维护者讨论实现的功能等技术问题；
  2. Mega 项目维护者将 Issue 的 Assignees 设为提交的同学，标识同意该同学的测试任务方案，可以针对此方案进行开发；
  3. Mega 项目维护者将 Issue 的 Type 设为 Task，Projects r2cn 的 Status 设为 In progress；
3

第三步：实现功能，提交 Pull Request

  1. 向 Mega 提交 PR：标题简要描写 PR 代码的功能，描述第一行写上 Issue 编号， 如 此 PR 完成了 r2cn 测试任务 #810 ，初始化时自定义分支名称 ，并且尽量在 PR 中描述功能和实现方案，便于 Mega 项目维护者 Review 代码；

注意事项:

  1. 代码中的注释使用英文，PR 和 Issue 中可以使用中文；
  2. 代码的测试用例尽量覆盖更多场景；
  3. 如果增加了命令的参数，需要同步修改 aria 模块对应的命令描述，PR 合入后对应的修改会自动更新到 Mega 网站 Libra 命令描述; 在 aria 是使用 Aira Docs 模板进行修改的，不能在 mdx 中使用 HTML 字符，可以使用模板提供的 Component 丰富页面展示，请参考 Components；
  4. 提交代码时使用 git commit -s -S 两个参数，用于 Signed-off-by 签名和 GPG 签名，否则代码 Review 后无法合入；
  5. 可以参考 Conventional Commits 规范编写 Commit Message、PR 标题和 PR 描述；
  6. PR 描述一定要加入测试任务 Issue 的编号，Mega 项目维护者才会知道此 PR 目标功能是什么，才能更有针对性的进行 Review ；
  1. Mega 项目维护者会优先使用 GitHub Copilot 进行 Review 代码，会生成 Review 意见，需要根据意见进行修改；
  1. Mega 项目维护者同时会人工 Review 代码，会生成 Review 意见，需要根据意见进行修改；
4

第四步：Mega 项目维护者合入 Pull Request

经过代码 Review 后，Mega 项目维护者会合入 Pull Request 。

注意事项:

对于测试任务，可以编写多个 PR ，每个 PR 完成一部分功能，这样可以更好的进行代码 Review 。

5

第五步：关闭 Issue

当 Mega 项目维护者认为 PR 已经完成测试任务，会将 Issue 的 Projects r2cn 的 Status 设为 Done 。此时同学才可以使用此 Issue 的链接，作为注册 r2cn 过程中需要提交的测试任务链接。

参考资料

  1. Rust 与 Git 版本管理，介绍 Git 底层原理的 Slide ，可以帮助更好的理解 Git 底层实现；
  2. Pro Git，官方最权威的 Git 书籍，可以帮助更好的理解 Git 功能和使用；
  3. Git - From Intern(al) To Expert - 正在编写中