Skip to content

Git Workflow

Jump to bottom
Haoqiong Bian edited this page Apr 1, 2022 · 4 revisions

Glossary

  • upstream (repo): the repository that we forked from, e.g., pixelsdb/pixels.
  • origin (repo): the forked repository under our own account.
  • local (repo): locally working repository cloned from the origin.
  • stable (branch): the default branch for stable codebase. All the changes made in this branch should be tested and reviewed. Currently, it is simply the master branch.

Principle: Issue First, Code After, and PR Finally

Describe what you're working on as an issue before you code. For a big issue with multiple stages, create a PR to merge the code of each stage into upstream. Finally, a solid PR closes the issue.

Workflow: Always Keep master Clean

After creating an issue, for example, Issue #100, we follow these steps to work on it: (1) use the master branch as the stable branch in our local repo. (2) checkout to a new branch named ISSUE-100 for this issue. (3) work on the new branch, make commits to this branch. (4) done with the new branch, checkout back to the master branch, pull from the upstream/master 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). (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 origin/ISSUE-100. (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 ISSUE-100
# fixing bugs ......
$ [ISSUE-100] git commit -m "fix long type error"
$ [ISSUE-100] git push origin ISSUE-100
$ [ISSUE-100] git commit -m "add long type test"
$ [ISSUE-100] git push origin ISSUE-100
$ [ISSUE-100] git commit -m "fix float type error"
$ [ISSUE-100] git push origin ISSUE-100
$ [ISSUE-100] git commit -m "add float type test"
$ [ISSUE-100] git push origin ISSUE-100
$ [ISSUE-100] git checkout master
# pull from the upstream and merge with local master
$ [master] git pull upstream master
# rebase remote changes to the new branch
$ [master] git checkout ISSUE-100
$ [ISSUE-100] git rebase -i master
# during rebase, we can squash small commits, and merge them into one.
# And write the commit message like:
# 
# [Issue #100] fix the bug...
# * 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
$ [ISSUE-100]git checkout master
$ [dev] git merge --no-ff ISSUE-100
$ [dev] git push origin master
# raise a PR for the bug fixing.

Releases

We can build a tag from the upstream/master for a released version.

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