[HOW TO] Commit and Code Review on GitHub

This is a blogging version of the guildeline on committing code to GitHub repository. The GitHub version is available here. You are welcomed to clone/fork and use them as your team's guildeline.

How to Contribute to GitHub Repository

This post introduces the approach to contribute your code into the (remote) GitHub repository. GitHub repository, public or private, allows a team of developers to asynchronously work on the same code base. The GitHub repository is extremely useful for teams to manage, review, test and deploy your code. This post will explain how to manage and review code on GitHub repository.

This post is a how to recipe. Although I assume readers having no background knowledge in git, I will not explain the concept of git and why we use it. This post can be useful for novice programmers who participate in projects that use GitHub repository to manage code.

Assumption

  1. You have a GitHub Account.

  2. Your computer has git installed.

  3. You have already clone the repository from GitHub. If not, you can clone by

git clone https://github.com/<user-name>/<repository-name>.git

Ground Rules

  1. The master branch is the stable branch. DO NOT PUSH CODE DIRECTLY TO THE master BRANCH.
  2. Developers should create a new branch and submit the pull request to merge code into master.
  3. Before merging any pull request, code review should be done. At least one approved review is required.

Workflow

The general workflow is illustrated above. Basically, there are three steps toward committing code into the repository. Each step will be elaborated in the following sections.

  1. Push the changes into GitHub and initiate a pull request (PR). link
  2. After the test phrase passes, another team member should review the code. link
  3. After the pull request has been approved, project leader can merge the code into the master branch. link

Commit and Push Code into GitHub

This example is based on Git Command Line.

1. Create a new branch

  1. Type git branch and see which branch you are currently in. If you are in the master branch, you will see

* master

  1. Remember, the master branch is the stable branch, which cannot be edited directly. So we should create a new branch with the copy of master branch by

> git branch dev

Naming the new branch dev is actually not recommended. Naming the new branch as a descriptive branch name such as specific feature name (e.g. frontpage) or developer's name (e.g. birkhoff-patch) might be a better choice.

Now we have two branches git branch

dev * master

  1. Go to the new branch

> git checkout dev

Now you are in dev branch

* dev master

2. Edit in the new branch

Edit code in the new branch.

3. Git Commit

Remember you are in the new branch while committing the code.

  1. Add changed files by

> git add [your-file-name]

or add all changed files by

> git add -A

  1. Commit to the local repository

> git commit -m "[commit message]"

Write descriptive messages such as "Add a front page", "Fix bug in header". A descriptive commit message can be helpful for future developers maintaining the same segment of the code.

4. Push code into the Repository

  1. Go to master branch first

> git checkout master

  1. Ensure the master branch is up-to-date

> git pull

  1. Go to dev again and push your code to the GitHub.

> git checkout dev > git push

You will find message requiring to specify the exact branch like

``` ^[[Afatal: The current branch hangzhi has no upstream branch. To push the current branch and set the remote as upstream, use

   git push --set-upstream origin dev

```

Follow the message

> git push --set-upstream origin dev

5. Now it is time to create a pull request in GitHub

  1. Log in your GitHub account.
  2. Go to our remote repository and select your committed branch. On your committed branch, you can find the Pull request button.
  1. After clicking the pull request, one following page will pop up. Select a reviewer to check the code and leave some comment if necessary.

Important: This workflow mandatorily requires code review before merging into the master branch. Selecting a reviewer can accelerate reviewing process.

Review and Merge Code

0. Test Phrase

Assuming the GitHub action has been correctly setup, the code will be automatically tested if the code has been pushed into the remote repository. If no testcases are written or the GitHub action is not setup, you can ignore this phrase.

1. Review Code

  1. The reviewer can check the changed code by clicking "Add your review".
  2. The reviewer can make comment, approve or request change.

2. Merge Code

If the code is approved, reviewer or the committer can merge pull request into the master branch.

how-to  git