Github

Revision as of 17:52, 2 January 2019 by Cyrus (talk | contribs)

Developing with GitHub

We have moved VisIt's main source code repository to github.

What do things look like now?

The good news is that less things changed than we originally expected.

We migrated these top level directories:

  • data
  • docs
  • src
  • test


Our develop git branch is now our default branch and is most similar to our old svn trunk The git repo contains RC branches since 2.0 Releases are tagged off of the RC branches, just like before.


Moving forward we will use a simple branch-based extension to our current release workflow.

The main difference is that all proposed changes will be done on a branch and vetted before they are merged into develop or any RC branch.

Restated: No direct commits to develop or any RC branch.

We will use continuous integration and code reviews as extra checks to avoid introducing errors.


To introduce this process, lets walk through changing a text file and creating a pull request to merge these changes.

The VisIt repo is hosted under the visit-dav GitHub organization.

https://github.com/visit-dav/

This walk through assumes are are a member of the visit-dav organization and have been added to the VisIt Developers team.


Create a branch with proposed changes

First, clone the Repo:


git clone https://github.com/visit-dav/visit.git


When you clone the default branch is the develop branch.


The first step is to create a branch off of develop, here is an example:


cd visit
git checkout -b task/cyrush/2019_01_update_github_map


Edit src/resources/github_usernames.txt and add a line with your username, full name, and organization - here is an example:

cyrush, Cyrus Harrison, LLNL


After making changes, you stage specific files to commit with git add


git add src/resources/github_usernames.txt


Finally, commit using:


git commit -m "Added my name to the github usernames file"


Once you have a set of commits you want to review, push your branch to github.


git push 


Create a Pull Request for your branch

Open up https://github.com/visit-dav/visit in your web browser.

After pushing, you should see a yellow box that asks if you want to create a Pull Request for your branch

Follow the prompts to create the pull request. Add cyrush as a reviewer and wait for approval. In the future, we will also have continuous integration checks that will need to pass before merging.


Merge your Pull Request

You can merge your pull request after continuous integration checks pass and you obtain approvals.

GitHub provides a few options to merge. The two methods we use are: Squash and merge and Create a merge commit. For most changes Squash and merge is preferred. Squashing turns all of the changes from the commits on your branch into a single commit in the target branch. If you have many or very complex changes, the other preferred method is to use a "Create a merge commit" This will preserve your branch commits in the target and create a commit that records the merge.


For this walk through use the Squash and merge option. When you Squash and merge, you have a final change to cleanup any commit messages. After you merge, GitHub provides a button to delete the source branch. Use it! This will help us avoid stale branches.



Setting up Git LFS

Git LFS (Large File Storage) is a mechanism to help revison control large files efficiently with git. Instead of storing large files in the repo, LFS provides an extension that stores small text files with meta data in the repo and the actual files on another server. These meta data files are called `pointer` files. We use LFS for binary data including our test data tarballs, regression test baseline images, and other ascents like shared binary builds of shared libraries.

Git LFS is not part of the standard git client. See https://git-lfs.github.com/ for how to obtain Git LFS.

When installing, use the following option:

git lfs install --force --skip-smudge


The "skip smudge" command sets up LFS in way that skips automatically pulling our large files on clone. We do this to conserve bandwith.


To obtain these files you will need to do some extra incantations followed by an explicit:

git lfs pull

Bash Shell Customization

If you use bash, you can add the following to your .bash_rc file to setup your shell to disable the current git branch.

PS1='[\u@\h \W$(__git_ps1 " (%s)")]\$ '