Git 是自由开源的分布式版本控制系统。

GitHub 是使用 Git 进行版本控制的代码托管平台。

准备工作

1. 你需要在系统上安装 git 来管理工作区。

   • Ubuntu

     $ sudo apt update
     $ sudo apt install git
     $ sudo apt upgrade
     

   • Manjaro (Arch Linux)

     $ sudo pacman -Syu git
     

     验证安装是否正确：

   $ git --version
   git version 2.23.0
   

   应该得到类似的版本信息。

2. 学习使用 Git
   Pro Git 第二版 是优秀的 Git 教科书，如此优秀以至于被直接放到 Git 网站上供大家学习。请跟随第一章完成 Git 的基本设置，学习第二章、第三章、第五章、第六章的 6.1、6.2、6.3 小节、第七章的 7.1、7.2、7.3、7.5、7.6、7.7、7.8、7.10、7.11，附录 C 提供了 Git 命令的索引。对具体的问题，可以在线搜索或群内提问。

3. 注册 GitHub 账号以访问考核仓库。
   Pro Git 的第六章已经介绍了 GitHub 的一些用法，GitHub Help 中还有更详细的内容。
   请将自己的 GitHub 用户名告诉考核负责人。

任务须知

1. 秋季实战时间为 9.27 至 11.4 (或 11.11，可能根据任务难度有所调整)，为期六至七周。前三周为基础考核任务，后三至四周为项目考核任务。请合理安排时间，认真对待考核。我们会根据大家考核期间的综合表现于11月中旬公布考核结果。
2. 考核标准将采用积分制，基础考核评分将划定标准线，项目考核评分将分为基础部分和发挥部分，我们将给每个人打分以保证公平性。
3. 基础好的队员可以快速完成已经掌握的部分，而着重完成后期的项目考核，对于基础薄弱的队员，请认真学习打好扎实的基础。整个考核都需要有 C++ 编程基础，如果对编程技能还不熟练请尽快学习。整个考核会比较有难度，希望你坚持下来，必将有所收获。
4. 基础考核有选修内容，选修内容不是必须的，但我们建议你掌握尽可能多的技能，这将会帮助你提高效率。项目考核要求你选择一个项目进行完成。
5. 请大家在每周的截止日期前按时完成规定任务。由于考虑到参与考核的人数较多，我们规定，基础考核的提交时间为【每周日的23:59分前截止】，项目考核的提交不早于最后一周，请在截止前按时上传。你可以根据自己的时间安排提前完成或先做后面的内容（但请不要提前上传），这并不影响考核结果。如果你提前做后面的任务，请遵守下文中考核流程检查单注意事项。如果有极其特殊原因需要推迟完成请在考核群内提前说明。
6. 请你们独立认真完成，不要抄袭其他同学的代码，我们将会仔细审阅每一份工程的代码。去年已发现有同学抄袭，一经发现你就没了。
7. 你们若有问题可以通过 Issue 的方式来提问，如果有推荐的学习资料可以 Pull request 来补充。
8. 请更多地通过 Issue 的方式来发起正式的讨论，可以使用 QQ 群发问 (现有队员会尽力解答)，多尝试通过 Google 获得解答。
9. 考核负责人的GITHUB用户名：李国锵(KCLI2000)、雷发兴(FaxingLei)、李金东(ADAMGALLAS)、吴孟霖(yyava)、王广烁(mysteryboxed)、邓贤杰(PumpkinJimmy)

积分制详细说明

我们会严格按照积分制进行评分。各阶段分数分布如下：

相关事项：

• 可自由推送更改到自己的工作仓库，但完成任务后提交 PR 要谨慎，我们以截止时间前的最后一次 Pull request 的结果作为标准。
• 我们鼓励大一学生积极参与，对于大一学生，所有部分的积分值会有 1.2 倍的加成。
• 积分值（包括细项）只精确到小数点后一位。
• 请在截止时间前及时提交你的代码，如果超过截止时间未提交，我们会视情况相应扣分（每迟交一天，应得分数会扣除 10%）。
• 如果最终版本里出现了错误文件，我们会视情况相应扣分。
• 考核相关负责人：李国锵、雷发兴、李金东、王广烁、吴孟霖、邓贤杰。
• 本评分标准最终解释权由中大空中机器人队所有。

任务成果提交方式

我们使用协作开发模式 (Collaborative development model) 完成考核，这篇文章介绍了如何在 GitHub 上合作。处于独立完成考核的原则，我们将结合 fork & pull 模式和共享仓库模式，考核仓库被设为 private，我们将把各位加入考核仓库的合作者列表，每个人创建对考核仓库的 fork 作为工作仓库。

下面说明两者的内容。

• 考核仓库：指这个仓库，考核题目会发布在这里，对所有人都相同。参加考核的同学都将被加进考核仓库的合作者，但此举只为让你获得浏览考核仓库和创建 private fork 的权限。考核过程无须克隆考核仓库，你可以在考核仓库的 GitHub 页面查看题目文件，浏览 Wiki，发起 Issue 或者 Pull request，参与 Issues 的讨论，但不允许直接修改考核仓库文件的内容，不能更改队员们设置的标签、Milestones、Projects 等 GitHub 功能，禁止改变 Issues 和 Pull requests 的状态。
  master 分支保存任务题目，其文件内容为：
  • tasks 考核题目，按任务阶段分为四个文件夹，其中包括题目说明、评分标准和程序资源。
  • wiki @ SHA-1 校验 项目 Wiki 子模块，里面保存 Wiki 页面的源文件。
  • .gitignore Git 文件，在其中指定不需要 Git 跟踪的中间文件。
  • .gitmodules Git 文件，记录子模块信息。
  • README.md 项目 README
  • logo.png 队伍图标
• 你的工作仓库：指每位同学对考核仓库的 fork，其原始内容与考核仓库相同，但所有者是你自己，在完成考核的过程中你将在工作仓库里与你的名字对应的分支答题，在该分支上你可以自由地将更改 push 到你的工作仓库，然后使用 Pull request 将成果合并到考核仓库。为了保证考核的独立，请将除考核负责人之外的其他同学从你的工作仓库合作者列表中移除，详细操作将在下文介绍。

准备工作仓库

要开始工作，你需要创建属于自己的工作仓库。打开考核仓库，点击 Fork 按钮创建一个考核仓库的 fork。

公平起见，请不要让参与考核的其他同学查看你的工作仓库，前往 Settings -> Collaborators，若有合作者，把除了考核管理员之外的其他同学从合作者中删除。

从 GitHub 上克隆工作仓库到本地。

$ git clone --recursive https://github.com/<你的 GitHub 用户名>/tutorial_2020.git
···
$ cd tutorial_2020

指定 --recursive 把 Wiki 子模块的内容一并克隆到本地，如果没有这么做，可以手动更新子模块。

$ git submodule init
···
$ git submodule update
···

检出到以自己名字命名的分支。

$ git checkout '你的名字'
···

请在这个分支下答题，不要写在 master 分支里。

为了能够方便获取考核题目的更新，你还需要将考核仓库也加入你的工作仓库的远程列表中，关于如何同步 fork，参考这篇介绍。现在，你在 GitHub 上的工作仓库存在于远程列表中，名为 origin，因此你可以自由 push 更改到工作仓库，接下来把考核仓库地址加入远程列表，命名为 upstream。

$ git remote add upstream https://github.com/SYSU-AERO-SWIFT/tutorial_2020.git

添加分支后，你需要将当前分支对应的远程分支设置为 origin/你的名字，使用 --set-upstream 参数。

$ git push --set-upstream origin '你的名字'

之后再使用 git push 时便会推送至正确的分支。

更新工作仓库

当题目更新或有其他重要资料发布在考核仓库时，你需要及时将更新同步到你的工作仓库。你可以打开考核仓库确认 master 分支最近的提交。

或者在你的工作仓库的 master 分支，查看其相对考核仓库的状态。

要更新题目，在你的工作仓库切换到 master 分支，然后从考核仓库拉取新提交，然后推送到你自己的仓库中。

$ git checkout master
···
$ git pull upstream master
···
$ git push origin master

现在 master 分支已经更新，你需要把更改合并到你自己的分支上。

$ git checkout '你的名字'
···
$ git merge master
···
# 解决可能发生的冲突并 commit
$ git push
···

请按照更新后的要求完成考核。

考核流程检查单

下面给出了每次工作时需要检查的事项作为参考。

1. 查看考核仓库确定是否有更新，若有，按上文操作同步到工作仓库。
2. 打开工作仓库，确认自己处在正确的分支，然后在 tasks 下每阶段对应的文件夹里面直接答题。
3. 取得一段进度后最好提交更改到自己的 GitHub 上保存，完成任务前你可以自由 push 自己的分支到你的工作仓库。
4. 在每个考核阶段的截止日期前完成对应任务，为标志着完成的一个 commit 打上标签并将其推送至 GitHub，然后在网页上发起 Pull request，详细内容在下文中介绍。因为每个人都能看到你的 Pull request，因此不要过早提交成果，建议在截止前的几个小时内再提交 PR。

注意！！！：如果你提前完成了这一段的任务，想提前做接下来的部分，请开一个新的分支工作，在这一段的任务提交结束后再将其合并回原分支。这是因为 Pull request 只指向当前分支的顶部，你对后面任务的更改在提交 PR 时其他同学会看到。

提交考核成果

请在每个考核阶段提交截止之前尽可能完成任务，当你决定提交成果时，请 commit 最后一次变更，并给这个特殊的 commit 打上标签，例如完成第一周任务时：

$ git commit -am "完成第一周任务"
···
$ git tag -a v1.0.0 -m "第一周成果"

我们约定完成第一周任务对应版本号为 v1.0.0，第二周为 v2.0.0，第三周为 v3.0.0，完成项目考核是 v4.0.0。提交后如果在截止前还有补充更改，请递增次版本号，禁止修改之前的任何 commits。之后将本地的更改推送到 GitHub，要把标签一并推送，需要显式推送标签。

$ git push origin --tags

push 完成后打开工作仓库的 GitHub 页面，切换到自己的分支，然后发起一个 Pull request。

填写信息前，确保 head repository 是你自己的工作仓库，base repository 是考核仓库，两者的分支都是你的分支。

请按照模板填写 Pull request 的标题和内容，与写文档相同，简要介绍一下你做的工作和其他想说的问题。

取消这个勾，别人就不能篡改你的提交。

右侧有五个标签位，请按如下介绍设置：

1. Reviewers: 这里可以 @考核负责人让他们来批改你的工作，请在这里点选所有考核负责人。
2. Assignees: 这里填申请人，也就是你自己。
3. Labels: 对 Issue 和 Pull request 进行分类，每个标签都有对应说明，请按实际情况选择，如果是提交成果，选择 submit，如果你是第一次使用这个功能，选择 First Issue!，各位会欢迎你的到来。
4. Projects: 这是自动进度更新系统，参加考核的同学提交成果请选择 评分进度跟踪，考核仓库编写进度跟踪 仅供考核负责人们使用。
5. Milestone: 这里跟踪考核总体进程，请按对应考核阶段选择一个，如第一周就选 Week 1。

填写内容完成之后请确认可合并状态，正确的 Pull request 应该可以直接被合并，我们不会接受发生冲突的 PR。

之后考核负责人会检查你的成果，合并 PR 后给出评分。正如之前提醒的，在你的分支的提交应该限制在本阶段任务之内，提交 PR 时才不会出现后面的内容，超前工作应该新开分支工作。