构建属于自己的项目

本章主要针对“如何构建一个属于自己的计算机视觉项目”为主题进行展开。

本章导航：

• 在 GitHub 上创建个人项目
• 利用 Git 子模块组织子项目

1 创建个人项目

由于构建个人或者公司的私有服务器涉及的知识点太多，本文考虑以 GitHub 作为远端服务器来构建个人项目。如果您的私有服务器已经搭建好了的话，直接把它当作 GitHub 进行操作即可。因而，本文介绍的创建项目的方法同样适用于私有服务器，区别不过是您提供的服务器的地址不同和仓库的使用权限不同而已。本节内容参考：https://opensource.guide/zh-cn/。

1.1 创建一个项目

第 1 步：在 GitHub（https://github.com/）上创建一个仓库，取名为 cv-actions，接着选择一个 LICENSE（如 GNU GPL v3.0，相关介绍见：https://zhuanlan.zhihu.com/p/56759711） 和 gitignore（选择 Python）。然后选择 settings：

往下滑动鼠标，找到 GitHub Pages，选择主题，随后便会生成一个网址：

接着，填写项目的简介：

第 2 步：将远端的项目克隆到本地。首先，按照下图操作获取项目的远程仓库地址（https://github.com/xinetzone/cv-actions.git）：

第 3 步：在本地电脑端打开 vscode 并在终端输入：

$ git clone https://github.com/xinetzone/cv-actions.git
$ cd cv-actions/

这样便在本地端拥有一个 cv-actions 的副本。

1.2 修改 README

对于一个项目来说，README（自述文档）是十分重要的。自述文件不仅仅是用于说明人们如何使用你的项目，还要解释你的项目为什么重要，以及它可以为你的用户做什么。在您的自述文件中，尝试回答以下问题：

• What：这个项目做什么？
• Why：为什么这个项目有用？
• How：如何开始？
• Help：如果需要，我可以在哪里获得更多的帮助？
• Who：谁维护和参与项目？

参考@PurpleBooth 的 README 模板 编写自述文档 README（https://github.com/xinetzone/cv-actions/blob/master/README.md）。其中的图标可以参考 github 编写 README 时如何获取 fork 等图标（https://xinetzone.github.io/zh-CN/f7c6a6b8.html）进行设计。

接着创建一些目录，这些目录均代表不同的功能。在项目根目录打开终端并输入：

mkdir data draft models outputs app notebook

• data/: 数据的存放
• models/: 模型的参数存储
• outputs/: 模型的输出结果
• app/：存放相关的 API
• notebook/：存放 jupyter notebook 等相关的文件
• draft/：(可以放置在任何位置)存放一些不成熟的或者未开发完成的一些相关内容，不被上传到 github

其中 data/，models/，draft/ 加入到 .gitignore 不被 git 管理。

进入项目的 Insights 栏目，选择 Community，您可以看到图5 的结果：

图5 列出了一个比较规范的项目需要满足的文件的清单。后续章节将逐渐填充检查清单。

1.3 编写贡献者指南

编写 CONTRIBUTING.md（贡献者指南） 文档有助于贡献者们快速了解如何加入本项目的贡献之中。下面介绍如何编写贡献者指南？

一般地，使用热情友好的语气并提供具体的贡献建议可以大大提高新人的参与度。比如，您可以在开头这样引入：

首先，非常感谢您为 cv actions 提供新鲜血液。正是更多像您这样的人，使得 cv actions 将逐渐发展为一个强大的计算机视觉社区。

1.3.1 准备工作1：创建 Issue 与 PR 模板

对于一个比较健全的社区，需要拥有一个优雅的 Issue templates（见图 5）。它可以令 Issue 的参与者有着一个统一而清晰的框架，同时，也方便其他人参与 Issue 的讨论之中。Issue templates 的创建可以直接从 GitHub 中需要选择一个模板，之后点击绿色按钮 Propose changes 提交修改即可：

当然，您也可以添加多个模板甚至自定义模板（具体细节见https://help.github.com/cn/articles/creating-a-pull-request-template-for-your-repository）。这些模板仅仅是一个雏形，还需要与后续的工作进行匹配。所以，刚开始先不用管这么多，先生成这些模板再说。如果需要创建有多个作者的提交，您可以参考 https://help.github.com/cn/articles/creating-a-commit-with-multiple-authors。

您还需要在 /.github/ 下创建文档 PULL_REQUEST_TEMPLATE.md 用于 Pull request（拉取请求，PR）的生成。因为编写良好的 PR 说明可以加速审阅者了解代码的预期结果的进程。它们也是帮助跟踪并应对每次的 commit（如测试、添加单元测试和更新文档）应执行的工作的好方法。更多优秀模板参考：https://github.com/XNoteW/github-issue-templates。下面以一个简单的例子来说明 PR 模板的样式：

非常感谢您参与到 cv actions 的项目中来，但为了创建一个良好的社区环境，在您提交 PR 之前，请您确保已经满足下列要求：

- [ ] 您的 code 是否已经还存在错误或者警告信息
- [ ] 您正在使用的术语（terminology）是否是社区约定的或者已经被公认的
- [ ] 您是否已经做过单元测试（unit tests）

一般地，一个相对优秀的 PR 应该包含如下问题：

• 您做了什么改变？
• 您修复了什么问题？
• 你发起的是一个 bug 修复(bug fix) 还是创建了一个新的功能？对旧的版本是否有重大影响？对已经存在的函数或者模块是否进行重构？
• 您是如何验证它的？

更多关于 PR 的细节可参考：https://github.com/embeddedartistry/templates/blob/master/oss_docs/PULL_REQUEST_TEMPLATE.md。

1.3.2 准备工作2：编写行为准则

一个社区想要可持续地且健康地发展需要拥有一份约定的行为准则：CODE_OF_CONDUCT.md。顾名思义，行为准则即是参与社区时的一些礼仪、说话方式、行为等，它帮助社区形成一种友好的氛围，且在某种程度上它也是展示项目对于贡献者的友好程度。

当前已经不需要我们自己创建行为准则，在贡献者公约(https://www.contributor-covenant.org/)之中已经提供了一份行之有效的行为规范，已经被用在包括 Kubernetes，Rails，以及 Swift等超过 4000 个开源项目(https://www.contributor-covenant.org/adopters)之中。参考图5 点击 Add Code of conduct，便会弹出图7 的结果：

选择贡献者公约（Contributor Covenant）并在右侧填写电子邮箱用于处理违反公约的行为和反馈。最后，提交修改即可。

1.3.3 贡献指南编写细则

考虑到项目的可读性，需要设计一些贡献指南编写的细则。如果您想要获得更多有关编写贡献指南的方式，可以查阅 @nayafia 的 贡献指南模板 或者 @mozilla 的 “如何构建 CONTRIBUTION.md”。下面给出 cv actions 的贡献指南：

# 贡献指南

非常感谢您乐意为 cv actions 提供新鲜血液。正是更多像您这样的人，使得 cv actions 将逐渐发展为一个强大的计算机视觉社区。

为了创建一个良好的社区环境，请您遵守我们社区的《[行为准则](CODE_OF_CONDUCT.md)》。如果您想要发起一个 Bug report 或者 Feature request，请您遵循 Issue 的模板进行贡献。同时也欢迎您贡献新的且实用的 Issue 与 Pull request templates。

请您仔细阅读这份指南，因为，如果您这样做了，既可以节省您的宝贵时间，同时也对其他贡献者或者审阅者们的极大的尊重。

本项目的**目标**是**打造一个健康且可持续发展的计算机视觉社区。**

## 贡献的类型

本项目不仅仅欢迎您贡献代码，同时也欢迎您贡献文档（请在 `/docs/` 中进行），教程或者本项目的使用手册等内容。

## 贡献的必要条件

1. 如果您不了解如何对项目进贡献，请您参考 [如何为开源做贡献](https://opensource.guide/zh-cn/how-to-contribute/)。
2. 为了方便项目的管理，请您使用 Git Flow 进行管理。当您将项目克隆到您的本地电脑后，请您运行：`git flow init` 并随之切换到 develop。具体是使用细节请 📖 <https://xinetzone.github.io/projects/>。
3. 本项目暂定以 Python 作为代码的开发语言，而文档的编写请使用 Markdown 进行工作。
4. 本项目在 GitHub 上维护的 master 分支作为预发布版本，而 develop 分支作为开发版本。其他功能版本请以 git flow 的规则进行管理。
5. 您贡献的 Python 代码需要支持 pep8，数学公式最好使用 markdown 的标准语法，比如 `$x^2=1$`等。

## Issue 与 Pull request 的行为准则

考虑到可读性与可理解性，在您创建 Issue 或者 Pull request（简写为 PR） 时，请遵循如下约定：

1. **请给出您的 issue 或者 PR 的 context**：即给出上下文语境。比如当您你运行程序时遇到一个错误，请解释你是如何操作的，并描述该错误现象是否具有再现性；当您提交一个新的idea，请您解释该 idea 您是如何想到的，并且说明您的 idea 的适用范围，是否可以将您的 idea 进行推广或者拓展。
2. **您是否已经完成准备工作**：请确认您是否阅读了项目的 README、文档、问题（开放的和关闭的），检查您的 issue 或者 PR 是否已经有人做过或者正在做，避免提交重复的议题或者请求。
3. 请您**保持请求内容的短小而直接**：每个人的时间和精力都是有限的，短小而直接的请求对大家都有益处。
4. **请保持您的优雅**：本社区禁止发布不良信息，注意用语文明而优雅，杜绝各种辱骂和打口水仗的行为。

## 获得联系

- 您可以在 Gitter @[cv-actions](https://gitter.im/cv-actions/community) 上讨论 Issue
- 如果有疑问，请您 ✉️ xinzone@outlook.com

## TODOS

- [ ] 利用 [pre-commit](https://pre-commit.com/) 自动部署代码的格式，使其自动化支持 pep8 等格式。

至此，我们便在 GitHub 上完成了项目的构建工作。

2 使用 git submodule 管理子项目

参考资料：https://git-scm.com/book/en/v2/Git-Tools-Submodules。

情景：在您正在维护的项目（可记为 A）中存在一些子项目或者第三方库（可记为 B）。您不想在 A 中直接维护 B，希望 B 作为一个单独的项目进行管理，这种情况下便需要借助 Git 子模块工具了。Git 子模块工具将 B 作为 A 的一个子目录进行管理，使用 git submodule 来实现。下面以一个例子来说明如何使用子模块的。

2.1 开始使用子模块

• 前提：在 Github 上单独创建一个独立的项目xinetzone/image(https://xinetzone.github.io/image/)，该项目是一个数字图像处理的工具包。
• 目标：在 cv-actions 项目中添加子项目 image。

第 1 步：克隆 cv-actions 到个人电脑。即在终端输入：git clone https://github.com/xinetzone/image.git。
第 2 步：git flow 初始化，即在终端输入如下命令：

$ cd cv-actions
$ git flow init

第 3 步：使用 git flow 创建并切换到新的分支 feature/image，即在命令行输入：

$ git flow feature start image

第 4 步：使用 git submodule 添加子项目 cv-actions 到目录 app/ 之下，即在命令行输入：

$ cd app/
$ git submodule add https://github.com/xinetzone/image

其中 https://github.com/xinetzone/image 是子项目 image 的网址。

此时，如果您运行 git status 查看项目 cv-actions 的状态，便看到：

从图8 可以看到此时在 app/ 下新增目录 image，且在根目录新增文件 .gitmodules。

其中 .gitmodules 文件记录了配置文件保存的项目 image 的 URL 与已经拉取的本地目录之间的映射：

[submodule "app/image"]
  path = app/image
  url = https://github.com/xinetzone/image

如果您有多个子模块需要被管理，.gitmodules 文件中就会有多条记录。虽然 image/ 是 cv-actions 的工作目录的一个子目录，但是，git 并不会将其视作普通文件进行管理，而是将其作为一个整体当作子模块中的某个具体的提交进行管理。

第 5 步：提交更改。为了让子模块 image 加入到 git 的历史（commit）之中，您需要将其提交：

$ cd .. # 回到根目录
$ git commit -am '添加子模块 image'

其中 -am 是 -a -m 的组合。

第 6 步：推送项目到远端分支 feature/image。

$ git push origin feature/image

2.2 克隆含有子模块的项目

克隆含有子模块的项目一般有两种方法：

• 方法1：git clone URL
• 方法2：git clone --recursive URL

下面先讨论如何使用方法1 克隆含有子模块的项目，首先使用语法 git clone -b 分支名 URL 克隆项目的指定分支。在终端运行：

$ git clone -b feature/image https://github.com/xinetzone/cv-actions
$ cd cv-actions/

此时，您进入 app/image 会发现其是一个空目录，这是因为含有子模块的项目需要进行初始化。初始化需要两步，具体操作是在 app/image 下面运行：

$ git submodule init
$ git submodule update

其中 git submodule init 用于初始化本地配置，而 git submodule update 用于从项目 image 中抓取所有数据并检出（checked out）父项目中列出的合适的提交。使用 git status 查看当前状态：

从图9 可以看出，此时 image 与其上游 origin/feature/image 已经同步了。

对于方法2，仅仅运行如下命令即可达到上述的同样效果：

$ git clone --recursive -b feature/image https://github.com/xinetzone/cv-actions

2.3 使用子模块

如果子模块的上游有的新的提交（commit），您想要获取更新，有两种方法：

1. 直接进入子模块所在目录 app/image 通过运行 git fetch 与 git merge，合并上游分支来更新本地代码。
2. 直接运行 git submodule update --remote image 获取上游分支来更新本地代码。

3 小结

本文主要讨论了如何利用 Git 与 Github 创建属于自己的项目，同时也介绍了如何利用 git submodule 在大项目中管理小项目。

notebook

笔记本