Revision as of 03:32, 3 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.

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

Create a personal access token if using two-factor authentication

If you have two-factor authentication enabled on your GitHub account and you fetch with HTTPS, GitHub will not let you use your actual password to authenticate. Instead, you will need to create a personal access token that you use when prompted for a password.

The following link points to a page for creating a personal access token to use for the password when accessing GitHub through the command line. Use the following scopes for the token:

  • repo:status
  • repo_deployment
  • public_repo

Create a branch with proposed changes

First, clone the Repo:

git clone

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 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.

After the remote branch is merged and deleted, you'll want to do two things on your local side:

(1) Update your list of remote branches

git remote prune origin
git remote update

(2) Delete your local branch. First switch to another branch (e.g. develop)

git checkout develop
git pull
git branch -D <name of your branch that was merged>

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 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 display the current git branch.

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

Things to Fix

  • any path with `third_party` in the name, was skipped due to regex matching
  • we need to find a way to prevent direct pushes to develop and rcs. We have github's seatbelts on, however these don't block admins (or owners) from pushing
  • lfs pattern matching does example as far as we (doc/*png does not match pngs in lower sub dirs)