Skip to content

如何参与WizNotePlus项目开发

Altair Wei edited this page Oct 23, 2020 · 2 revisions

GitHub 与 Git 工作流程

1 基本工作流程

一个典型的 GitHub 工作流程可以参考:https://github.com/thoughtbot/guides/tree/master/protocol/git

img

1.1 Fork 上游仓库到自己的账户

使用 GitHub 提供的 fork 功能,创建属于你的远程仓库。

1.2 将你的远程仓库克隆到本地

通过 git clone git@github.com:USERNAME/WizNotePlus.git 将远程仓库克隆到本地。

然后添加 upstream 指向上游仓库:

git remote add upstream https://github.com/altairwei/WizNotePlus.git

检查 upstream 是否添加成功:

git remote -v
# 以下为输出结果:
# origin git@github.com:USERNAME/WizNotePlus.git (fetch)
# origin git@github.com:USERNAME/WizNotePlus.git (push)
# upstream https://github.com/altairwei/WizNotePlus.git (fetch)
# upstream https://github.com/altairwei/WizNotePlus.git (push)

1.3 依据分支管理策略新的分支

任何代码的改动都要在新的分支中实施,具体请参考后文的分支管理策略。

例子:

git checkout -b feat/new-editor

1.4 修改代码并提交

依据你的需求对代码进行修改,提交日志的编写请参考后文。

1.5 同步上游仓库

在开发过程中经常需要与上游进行同步,例子:

git fetch upstream
git rebase upstream/master
# 或者另外一种方法 (不推荐) :
git pull upstream master

我们推荐使用 rebase 命令同步更新,避免产生有冲突的提交。

1.6 整理合并多个提交(可选)

分支开发完成后,很可能有一堆commit,但是合并到主干的时候,往往希望只有一个(或最多两三个)commit,这样不仅清晰,也容易管理。

如果你对 git rebase -i 或者 git reset 的用法很熟练,那么可以选择将冗杂的提交整合到一起。比如在开发过程中有多个 WIP 类型的提交,那么就可以选择使用 git rebase 将这些提交整合成一个。具体教程可以参考 Git 使用规范流程 - 阮一峰 中的 “第五步:合并commit” 。

提交的整合依然需要遵守 “一个提交只做一件事” 的原则。

1.7 推送到远程仓库

修改完成后你就可以推送本地更新到你自己的远程仓库了。

1.8 发出 Pull Request

请参考本项目 “分支管理策略” 向上游仓库发出 Pull Request 。

2 分支管理策略

  • master 分支:只允许 develop 和 hotfix/* 分支合并进来。
  • develop 分支:如果 bugfix 非常简单,仅需要一个提交就可以完成,那么可以直接在 develop 分支修复BUG,而不必要开辟一个新的 bugfix/* 分支。
  • feat/* 分支:新的特性开发需要新建一个分支。
  • hotfix/* 分支:比较紧急的问题。一般从 master 中分支出来,修复后合并到 master 分支。
  • bugfix/* 分支:修复一般性问题。
  • wip/* 分支:某些未完成的工作需要同步。

3 提交日志编写

3.1 日志模板

提交commit时,必须给出完整扼要的提交信息,下面是一个范本。

Present-tense summary under 50 characters

* More information about commit (under 72 characters).
* More information about commit (under 72 characters).

http://project.management-system.com/ticket/123

第一行是不超过50个字的提要,然后空一行,罗列出改动原因、主要变动、以及需要注意的问题。最后,提供对应的网址(比如Bug ticket)。

3.2 标题类型

提交消息的第一行我们暂且称之为 “标题”,请使用以下单词注明提交类型:

  • NEW: 当你添加一些全新的东西时使用。
  • IMPROVE: 用于改进或增强代码段,比如重构等。
  • FIX: 修复 bug 时使用。
  • DOC: 添加文档时使用,比如 README.md 。
  • RELEASE: 发布新版本时使用,比如 “bump version” 。
  • TEST: 添加测试用例等待。
  • WIP: work-in-progress ,代表这这个提交随时都有可能被重置,请勿依赖于该提交。

比如:NEW: add a rich text editor.FIX: unable to save content.

4 语义化版本号信息

master 分支中的每一个 “最新提交” 都应该是一个可发布的版本,因此有必要为它们都 git tag 上相应的版本。

版本格式:主版本号.次版本号.修订号,版本号递增规则如下:

  1. 主版本号:当你做了不兼容的 API 修改,
  2. 次版本号:当你做了向下兼容的功能性新增,
  3. 修订号:当你做了向下兼容的问题修正。

先行版本号及版本编译元数据可以加到 “主版本号.次版本号.修订号” 的后面,作为延伸。

5 参考资料