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:
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.
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
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:
The following link describes how to add your ssh key to your GitHub account.
Create a branch with proposed changes
You can access GitHub either through https or ssh. If you use the https you will be prompted for your password whenever you push to GitHub. There are ways you can have your password cached for a period of time to reduce the frequency of entering your password. However, if you have two-factor authentication set up you will need to create a personal access token to use in place of the password. If you use the ssh protocol you can set things up so that you never have to enter a password by adding your ssh key to your GitHub account.
First, clone the Repo:
git clone https://github.com/visit-dav/visit.git
git clone ssh://firstname.lastname@example.org/visit-dav/visit.git
Setup our hooks:
cd visit ./scripts/git-hooks/install-hooks.sh
When you clone the default branch is the develop branch.
The first step is to create a branch off of develop. This is where your proposed changes will be done, then once pushed will be vetted, will be merged into develop (or RC) branch. Here is an example:
git checkout -b task/cyrush/2019_01_update_github_map
- Note - There is no definitive prescription for naming your branches. We have not converged yet on if there will be.
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
- Note: git add is what you use both to add a new file and to stage changes to an existing file. You can also use git add -u to stage modifications to any file git already knows about.
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 may complain about not knowing where to push.
There is no tracking information for the current branch. Please specify which branch you want to merge with. See git-pull(1) for details. git pull <remote> <branch> If you wish to set tracking information for this branch you can do so with: git branch --set-upstream-to=origin/<branch> task/cyrush/2019_01_update_github_map
Here is an example:
git branch --set-upstream-to=origin/task/cyrush/2019_01_update_github_map task/cyrush/2019_01_update_github_map git push
If you would like your local branches to automatically reference an upstream branch, configure your default:
git config --global push.default current
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.
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>
- Note: Branching in git is cheap. If you want to make more changes - it's best to create a new branch. Particularly - if you use a squash merge, your current branch won't align with the updated develop branch.
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 Todo
- Add info + links on how to clone with SSH
- Add info about setting up hooks
- Basic CI style checks
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)
- revisit email mappings