Skip to content

Git Workflow

Jump to bottom
Guodong Jin edited this page Jul 25, 2019 · 4 revisions

Glossary

  • upstream (repo): the repository that we forked from.
  • origin (repo): the forked repository under our own account.
  • local (repo): locally working repository cloned from the origin.
  • dev (branch): the default branch for currently actively developing codebase. it can simply be dev or a current version vx.x.
  • base (branch): the default branch for currently stable codebase. we refer this to master currently.

Principle: Issue First, Code After, and PR Finally

I think it might be a good practice to describe what you're working on as a issue first before you code, so others get to know what you're working on, and you can motivate yourself with a detailed plan and a clear goal. Finally, a solid PR closes the issue. However, for some quick commits that is so simple and evident itself (like fixing a typo in the documentation), I think we can save the time for issues and just work on it directly with a clear commit log.

Workflow: Always Keep Master Clean

I assume the workflow should cover following scenarios:

  1. adding a new feature to the codebase.
  2. fixing bugs in existing stable codebase.
  3. resolving issues. this will cover above two in most time.

If everything is in order, we do one thing at a time locally. And in this case, we: (1) maintain a dev branch as the development branch in our local repo. (2) checkout to a new branch for each assignment, like issue#x, feature-x, etc. (3) work on the new branch, make commits early and often to keep tracking of changes, and sync with the origin repo for checkpoints. (4) done with the new branch, checkout back to the base branch, pull from the upstream dev branch to see if we fall behind, and checkout back to the new branch, rebase new commits from the upstream and resolve conflicts if any exist. (5) the rebase can be interactive to squash several commits into a single descriptive commit. this is to prevent lots of small commits make the commit history ugly. (6) now merge our new branch locally, and push back to the origin. (7) raise a PR in the origin, push new commits to the upstream dev branch.

An example would be like this.

$ [dev] git checkout -b 13-BUGFIX-type_error
# fixing bugs ......
$ [13-BUGFIX-type_error] git commit -m "fix long type error"
$ [13-BUGFIX-type_error] git push -u origin 13-BUGFIX-type_error
$ [13-BUGFIX-type_error] git commit -m "add long type test"
$ [13-BUGFIX-type_error] git push origin 13-BUGFIX-type_error
$ [13-BUGFIX-type_error] git commit -m "fix float type error"
$ [13-BUGFIX-type_error] git push origin 13-BUGFIX-type_error
$ [13-BUGFIX-type_error] git commit -m "add float type test"
$ [13-BUGFIX-type_error] git push origin 13-BUGFIX-type_error
$ [13-BUGFIX-type_error] git checkout dev
# pull from the upstream and merge with local dev
$ [dev] git pull upstream dev
# rebase remote changes to the new branch
$ [dev] git checkout 13-BUGFIX-type_error
$ [13-BUGFIX-type_error] git rebase -i dev
# during rebase, we can squash small commits, and merge them into one.
# And write the commit message like:
# 
# [#13] BUGFIX: type error
# * fix long type error
# * add long type test
# * fix float type error
# * add float type test
#
# In this way, we can compact many local small commits into a big one, and make commit history clenan.

# merge our new branch into local and commit to origin
$ [13-BUGFIX-type_error]git checkout dev
$ [dev] git merge --no-ff 13-BUGFIX-type_error
$ [dev] git push origin dev
# raise a PR for the bug fixing.

Releases

The dev branch will be merged into the base branch when they're stable, and hopefully we can release a new version after each merge with a release note.

Tips

Ref logs

git log -g is a good start to find your lost/hidden commits. If you don't want to browse all commits manually, try searching it (git log -Sfoo -g).

Git merge

git merge --squash branch-x will produce the working tree and index state as if a real merge happened (except for the merge information), but do not actually make a commit. git merge --no-ff branch-x will create a merge commit even when they can be fast forwarded.

Git stash

git stash is a good tool to save local modifications away and reverts the working directory to match the HEAD commit.

Clone this wiki locally