Version Control¶

contributors: Yao Jiayuan
last updating date: 2021-05-22

MIG uses Git and Github to manage softwares and documents.

All the members SHOULD NOT push revisions to the main branch of all the public repositories. All the memebers MUST NOT push revisions to the main branch for private repositories either. Instead, all the revisions must be reviewed and approved using Pull Request.

We present some a simple tuturial below. Please refer to seismo-learn/contributing to learn more.

Git¶

Git is a fast, scalable, distributed revision control system with an unusually rich command set that provides both high-level operations and full access to internals. Please refer to the following references for details.

A list of some commonly-used git commands:

# clone a remote repository to your local computer
$ git clone git@github.com:username/repository_name.git

# add the revisions in one file or all the files to Index
$ git add filename
$ git add --all
# commit the revisions to HEAD
$ git commit -m "revise filename"

# push the revisions to remote repository
$ git push origin master

# create and go to a new branch
$ git checkout -b bug_x
# go to master branch
$ git checkout master

# delete a fully merged branch
$ git branch -d bug_x
# delete a branch
$ git branch -D bug_x

# fetch and merge the revisions in remote repository
$ git pull
# merge revisions at branch bug_x to current branch
$ git merge bug_x

GitHub¶

Github provides hosting for software development and version control using Git:

A list of some commonly-used commands in GitHub command-line tools:

hub: an extension to command-line git that helps you do everyday GitHub tasks without ever leaving the terminal:
```
# fast-forward all local branches to match the latest state on the remote
$ hub sync
```

GitHub CLI: take GitHub to the command line:

# create a pull request and request reviews by
# core-man, HouseJaay, Shucheng-Wu, tianjueli
$ gh pr create --reviewer core-man,HouseJaay,Shucheng-Wu,tianjueli

Workflow¶

We use the repository, MIG_Docs, as an example to show how we should revise and update a GitHub repository on which at least two authors are working.

Branch protection rules is used to protect the main branch, along with two activated rules:

Require pull request reviews before merging: 1 reviewer
Include administrators

We use the following pull request merging method:

Allow squash merging
Automatically delete head branches

Preparation¶

clone the remote repository if it is the first time:
```
$ git clone git@github.com:MIGG-NTU/MIG_Docs.git
```

Maintainment¶

Update the local branches from remote since others may revise the remote branches:

# frist way: use hub
$ hub sync

# second way: use git pull
$ git checkout main
$ git pull

Create a feature branch (e.g., feature_x) in which we update and commit the revisions:
```
$ git checkout -b feature_X
```
Do some revisions on the feature_X branch, and check them by building the repository locally at the same time. You have to install Sphinx and Read the Docs Sphinx Theme to build the website locally:
```
# build the website locally
$ make html

# check the website in a website browser (e.g., google-chrome)
$ google-chrome build/html/index.html&
```

Commit the revisions. You can do the revisions and commit them for many times:

$ git status
$ git add --all
$ git status
$ git commit -m "leave a revise message here"

When you do the revisions locally, the remote main branch may be updated. So, we could choose to synchronize with the remote main branch:

# first way: synchronize with remote main branch using hub
$ hub sync

# second way: synchronize with remote main branch using git pull
$ git checkout main
$ git pull

When you revise the content, there could be many commits. Some commits may be not so important. You can squash some commits into one or several commits so that the revisions are clear and easy to manage:
```
$ git rebase -i main
```
When you think the revisions are okay, create a pull request and request at least 1 reviewer:
```
$ gh pr create -r core-man,HouseJaay,Shucheng-Wu,tianjueli
```
Review/Approval/Merge on GitHub
- The reviewers review the commit by commentting and/or approving it online
- If everything is fine, the author can go to the GitHub website to merge the commit
- If there are conflicts, the author needs to resolve them locally and push to remote again
- When commits are merged, the feature_X branch will be automatically deleted in Github

When commits are merged, we have to update the local branches:

# update the local branches since the remote master has been updated
$ hub sync

# checkout to main branch
$ git checkout main
# delete local feature branch
$ git branch -D feature_X

In summary, we first add revisions in a local feature branch, and submit a pull request. If it is approved and merged to the remote master branch, we then have to update the local main branch with the remote one. At last, the local feature has to be deleted.