在Github上托管项目代码

Posted by Hsz on November 1, 2020

在Github上托管项目代码

Github是一个相当成熟的代码托管平台,我们除了可以在上面找开源项目外,更重要的是可以借助它自己构建自己的开源项目.

不要认为只有大型开源项目才是开源项目.

开源项目本身并不一定是直接可用的软件,也可以是一个包,一个简单的命令行工具等;为开源项目贡献代码也不一定要真的参与编程,为它写文档,提工单也是在为开源项目做贡献. 这些都可以在Github上实现.

使用Github记录灵感

Github提供一个叫gist的服务可以用于记录文档和代码片段.这个服务需要翻墙才能使用有点遗憾,但如果可以使用还是很方便的.我们很多时候灵感都是只言片语和不成体系的代码.很多时候这些灵感稍纵即逝,我们也不知道它是否值得投入精力将它变成成体系的项目.这种时候最好的办法是记录下来,当然你随便找个word,甚至拿个纸笔记下来也可以,但往往灵感需要积累到一定数量才能出现真正有价值的,而随意记录很容易丢失不能形成规模.在奔跑吧，程序员：从零开始打造产品、技术和团队一书中有过相似的描述,记录灵感也是创业过程中需要关注的点.我想这也就是Github gist服务的初衷吧.

要使用Github gist可以点击个人头像左边的小加号,在弹框中选择New gist.

进入 gist

我们会进入创建页

new gist

在里面写上你的灵感保存就好了.要查看以前写gist的可以点击右上角view your gist

gist list

gist也可以评论也可以fork也可以收藏.和对代码仓库的关注方式基本一样.我们也可以在顶栏左上角的All gists中查看到其他人的gist.

题外话:Github中的代码仓库命名空间和特殊代码仓库名.

Github中代码仓库都是在命名空间下的,一个典型的代码仓库地址类似https://github.com/<命名空间>/<代码仓库名>. 命名空间隐式的包含了从属关系.Github中包含两种命名空间:

  • 账号命名空间

    当你注册了一个github账号,那么你的用户名就成了一个命名空间,你在自己账号下创建的所有代码仓库就都属于这个你账号为名字的命名空间了. 这种命名空间下的代码仓库默认只有账号的所有人才可以做push操作.

  • 组织命名空间

    组织命名空间需要由登录账号创建.在人头像左边的小加号,在弹框中选择New organization就可以创建一个组织.

    新建组织

    新建组织过程中会让你提交用途等信息.创建过程中会有个可选项是让你邀请成员组成Team.这是因为组织的设计目的接近开源群组的概念,本身是用于让一群人管理一组项目的.因此组织内有团队管理页面,有团队日志审计页面,同时也有成员的权限管理页面.

    个人使用的化更多的可以把组织命名空间用作代码仓库的归类工具方便自己管理.

命名空间中的项目管理都是一样的,每个命名空间都有一个特殊的仓库名<命名空间>.github.io用于借助Github Pages服务构造命名空间的描述文档.如何使用Github Pages我们会在后面介绍.

创建一个代码仓库

在右上角头像边的加号上可以创建账户命名空间下的代码仓库,而组织页面右上角的New按钮可以用于创建组织命名空间下的代码仓库.

新建仓库

我们可以选择公开或者私有自己的代码仓库,在以前github对私有代码仓库是收费的,现在页免费了.不过如果是开源项目建议公开.

Github给出了一些.gitignore的模板,不过老师说并不是很全面,一般都还是需要按自己的需求修改的.

创建好后就只需要clone到本地就可以开始你的开发了.

为你的代码仓库建立文档

无论是从便于维护的角度还是从便于分享的角度,你的项目都应该维护好自己的文档.

Github包括其他代码托管平台都会提供以下工具用于文档建筑.

  • 对根目录下README.md的渲染,有的也可以渲染README.rst比如Github
  • 项目wiki服务的支持(多数支持)
  • 项目静态页面支持(Github,Gitlab有支持)

通常他们是按必要性依次下降的.下面做详细介绍

利用README简单介绍代码仓库

一般来说README是每个项目必备的文件.它是对整个项目的快速入口,一些比较简单的项目可能文档就只要README就够了.

通常README需要描述如下几个方面

  • 项目元信息介绍
    • 版本
    • 状态
    • 作者
    • 作者email
  • 项目简介,介绍功能
  • 项目依赖
  • 项目关键字
  • 项目特性
  • 安装方式
  • 使用方式示例
  • 使用限制
  • 要做未做的特性

一般长期维护的项目还会有一个专门CHANGELOG.md用于描述版本变化.一个比较靠谱的模板如下:

# v0.0.0

## Bugfixes(修正bug)

1. xxx
...

## Features(新特性)

1. xxx

## Deprecations and Removals(进入过时的特性和删除支持的特性)

1. xxx

## Performance Optimizing(性能优化)

1. xxx

## Improved Documentation(文档更新)

1. xxxx

## Dependencies(依赖变化)

1. xxx

# v1.0.0

...

版本变化一般不是给用户看的而是给开发者看的.

利用Wiki托管开发文档

利用Wiki托管开发文档

在Github代码仓库页的顶部可以进入wiki选项卡,在其中我们可以建立一个多页的文档,在比如Gitlab,gitea中都有类似功能.

由于wiki服务的位置比较不易到达,因此如果要用的话比较适合放置开发文档.

开发文档的主要作用是向开发者解惑项目.所以会和一般的用户使用文档不太一样.

内容通常包括

  1. 项目结构
  2. 开发规范
  3. 测试方法
  4. 常见问题

当然了并不是所有项目都有必要使用Wiki服务.通常符合如下特点的项目才应该使用:

  • 参与人员比较多
  • 项目历史比较长

构建项目主页

如果你的项目是一个面向一般用户的产品,那么一个好看规整的项目主页是一个很大的加分项.

但是通常来说构造项目主页意味着可能有一定成本,这个就需要取舍了.

项目主页一般来说是更加细致化的README,会详细介绍项目的使用方法和注意事项,同时往往也会提供接口文档方便查阅.

利用Github Pages创建项目主页

Github提供了Github Pages这个静态网站托管服务,你可以免费的获取一个二级域名以及一个静态网站托管服务,还是很值的. 如果你觉得二级域名不行,它也支持配置你自己的域名,最多就是花个几十块买个域名就够了.

任何一个项目都可以使用Github Pages功能.在项目的Setting选项卡中你可以找到Github Pages的相关配置

配置github pages

我们可以指定一个位置(指定分支/指定文件夹)作为托管目录存放静态网页文件或者渲染工具的源文件.也可以在Custom domain上指定用户的域名.

项目如果没有指定域名,那么Github会自动分配给他一个域名.域名的分配规则是:

  1. Custom domain上指定用户的域名则使用指定的域名
  2. 如果项目为命名空间中的特殊仓库(<命名空间>.github.io),那么会得到一个默认二级域名http://<命名空间>.github.io,访问uri的第一级为/,也就是访问路径为http://<命名空间>.github.io
  3. 如果项目不为命名空间中的特殊仓库(<命名空间>.github.io),且特殊仓库已经指定了域名,则使用特殊仓库指定的域名,但访问项目的uri第一级为项目名,即``http://<特殊仓库指定域名>/<项目名>`
  4. 如果项目不为命名空间中的特殊仓库(<命名空间>.github.io),且特殊仓库没有指定了域名,那么会使用默认命名空间的二级域名,访问项目的uri第一级为项目名,即``http://<命名空间>.github.io/<项目名>`

配置自定义域名

要配置自定义域名首先你得先买个域名,哪里买都行.

然后就是配置了.配置的步骤如下:

  1. 在Setting中Github Pages->Custom domain中填写你申请的域名,然后保存
  2. 在托管目录的根目录中新建一个CNAME文件,其中填上你申请的域名

  3. 到你买域名的供应商那边进行域名解析,有如下几种情况:

    • 二级域名,比如blog.xxxx.xx这种

      选CNAME作为解析方式,然后把自己的原始网址放上去就行了.

    • 一级域名和www域名 除了要用CNAME外,还需要用A解析.只要在A解析中选好,没有二级域名就解析@,有www就额外加上www,ip地址填上

      1. 192.30.252.153
      2. 192.30.252.154

这样等到到域名解析生效你就可以用自己的域名访问部署的静态页面服务了.

Github Pages默认使用Jekyll作为静态网站生成器,我们也可以在托管目录下创建空的.nojekyll文件来关闭Jekyll渲染从而使用其他前端技术. 下一篇文章开始的3篇文章将介绍Jekyll在内的常见好用的静态页面生成工具.

项目管理

目前市面上的Git服务都是使用Issue(工单系统)配合Pull Request进行项目管理的.前面一篇文章中介绍的Github Workflow便是基于这两样工具建立起来的.

在这两个之上,许多Git服务也会提供里程碑计划支持用于聚合整理工单. 许多Git服务还会为工单提供标签系统用于归类整理工单便于管理.

Github作为这个领域的标杆当然这些功能都有.下面我们开始介绍如何利用这些工具做项目管理.

在Github下工单同样也和Pull Request的Merge操作以及Github提供的看板服务Github Project可以联动.这些后面也都会有介绍.

分支保护

git天生的缺陷之一就是缺乏对权限的控制.github中我们可以使用分支保护功能来控制权限.

在仓库的setting中可以找到branches选项卡,我们可以在其中设置分支保护规则.

分支保护规则

我们可以在其中设置匹配规则来针对特定分支设置

分支保护设置

规则中比较重要的是Require pull request reviews before merging和Require status checks to pass before merging,这两条可以保护分支必须通过pull request来执行代码更新.

管理你的(Issue)工单

几乎所有的Git服务的项目管理功能都是基于工单的.在Github中我们可以在代码仓库顶部找到工单相关的页面.

工单页

这个页面提供了查找已有工单的搜索框,创建新工单的入口,以及管理与工单相关的标签和里程碑的入口.点击进去就可以看对应工单的内容.

工单详情

工单类似知乎里的一条问题,会有问题部分,评论部分,因此一般来说我们会引导工单的内容内聚的不是发散的展开.一般情况下每个登录用户都可以写评论,评论区也支持富文本.

而管理相关的部分则包括:

  • 操作记录部分,可以看到谁做了什么
  • 与管理工具联动部分,这部分集中在右侧,可以关联标签,处理人,项目,所属里程碑以及关联的Pull request
  • 关闭工单按钮,评论区有个按钮可以关闭评论,当结单时我们就可以关闭工单,关闭工单只是让工单变成关闭状态,还是可以继续评论,也可以重开工单.

规范你的工单

Github提供了工单模板,我们创建模板后提交工单就可以选择模板进行编辑了.这有助于我们规范工单更加方便的定位问题.

这项功能在项目的设置页中的feature段

开启工单模板

点击setup templates后进入工单编辑页面,我们可以设置两种工单模板

  • bug提交模板
  • 特性提交模板

同时也可以自己定义自用模板

定义模板

点击模板的Preview and edit可以编辑模板内容.一般默认的已经相当全面.但我们也可以做的更细致些.

编辑模板

使用标签归类你的工单

在工单页有一个项目是Labels,进去后就可以编辑项目工单的标签了.

标签编辑

工单标签的作用是归类工单.一个工单可以关联多种标签.Github默认会给出10种标签:

  • bug提交一个bug
  • dependencies更新依赖
  • documentation改进文档
  • duplicate工单或者pull request已经存在,这种标签的一般要关联到已经存在的工单
  • enhancement发起新特性
  • good first issue给新手的工单,让他们可以从简单的入手加入项目
  • help wanted求助工单
  • invalid工单不合要求
  • question工单描述信息不足
  • wontfix拒绝工单的要求

如果是赶进度的项目我们应该再创建一些用于体现急迫程度,优先级的标签,工单可以使用一个组合的标签–类型,急迫程度

在Pull Request中关联你的工单

工单最基础的用法是结合Pull Request功能.毕竟工单只是描述,实际解决问题是靠的代码.

当我们为某个工单解决问题后我们应该提交一个Pull Request到项目上

创建一个pullrequest

在项目顶栏的pull requests页可以看到所有的拉取请求,点右上角new pull request创建一个新的拉取请求

对比分支

这之后我们需要选择仓库的分支做对比,查看文件变化以确定是否是可以merge的状态.选好后创建pull request.

创建pull request

我们可以在这个页面选择关联的code reviewer,责任人,里程碑和项目.同时为这个pull request添加说明.

在创建完成后会进入如下页面来追踪这个pull request

拉取请求追踪

这个追踪页面中我们可以关联工单.也可以在其中进行代码审查,评论,执行最终的合并操作.

使用里程碑串联你的工单

通常的开发过程是我们会为项目定一个计划,这个计划包含若干的新功能,若干的bug修正,若干的性能优化等,我们按计划执行版本的迭代. 每一个版本的计划就是一个里程碑(milestone).在Github中我们可以使用里程碑功能将若干的工单组织起来,这些工单包括bug,包括新特性等.

类似标签,我们可以在工单页进入里程碑的管理.

里程碑

进去后可以看到每个里程碑的进度以及其中包含的工单.我们也可以点击右上角床架新的里程碑或者点击一个里程碑进去编辑.

创建里程碑

使用里程碑可以让你的项目更加可控.虽然Changelog也可以记录每个版本的变化,但里程碑配合工单和pullrequest会更加具体.

使用Github Project构造看板

不同于上面介绍的项目管理工具,Github Project更接接近敏捷开发中的看板方法

Github Project提供的看板是可以跨仓库的,这也就为跨模块协调提供了可能.

我们可以在顶栏的找到Github Project的入口

git project入口

这个入口可以创建一个未关联仓库的git project项目.

创建看板

这里有两个注意点

  1. 我们可以在Project template中选择模板,推荐使用automated kanban
  2. 我们可以在Linked repositories中选择要关联的项目,这里可以关联多个仓库.如果缺省,那么下次工单或者pull request关联到这个project时,这个project就会自动成为这个仓库的专属.

我们也可以在仓库顶栏的project中创建看板,过程类似.

在创建完成后我们就可以进入看板

看板

默认的看板只有3列

  • todo,基本可以理解为需求池

  • in progress,基本可以理解为开发中的需求

  • done,基本可以理解为完成的需求

每一列中可以有多项被称作card.card可以是笔记,工单,pull request三种类型.我们要做的就是把不同的卡片拖动到不同的列来追踪进度.

之所以推荐使用automated kanban是因为这个模板会默认将关联项目的工单和pull request都做成card,并且给你设置好哪些事件可以自动的移动card.

如果我们要自定义这个自动移动的事件,可以在每一列中点击设置

编辑自动化1

点击其中的manage automation进去修改

编辑自动化2

发布你的项目

如果你的项目是那种按版本发布的软件包而不是线上服务,那么你甚至可以在Github上发布编译好的二进制包.

github上发布包有两种方式:

  • Github Package这个服务目前只支持少数几种编程语言,它的作用是将你的包发布到对应的中心化包管理工具,比如npm
  • Github Releases这个服务可以将你编译好的二进制包或者可执行文件发布上去,同时在仓库上用当前的master分支的HEAD打个tag.

发布包

我们比较常用的是Github Releases,毕竟package服务的功能我们完全可以手动完成.

Github Releases首先是让你给打个标签,这样当前的源码就下来了,一个release的版本也就生成了.之后我们可以自己再编译压缩什么的将二进制版本的包上传上去.

这一特性非常适合发布客户端一类的东西.

由于Github Releases自带tag功能,因此我们也完全可以用它做项目版本管理,在每个版本的说明中详细介绍变动.下面就是redis的一个gui客户端AnotherRedisDesktopManager的发布页

发布好的包

POST TAGS
POST Category
introduce