2. Developing at GitHub¶
The VisIt project has a number of repositories located at the GitHub visit-dav organization.
The primary repository for doing VisIt development is the visit repository.
The following top level directories exist in the visit repository.
- data - Data files used by the test suite.
- docs - Legacy documentation including design documents and presentations.
- scripts - Various scripts used for doing VisIt developement including scripts for managing docker containers and doing continuous integration.
- src - The VisIt source code. It includes the Read the Docs documentation and the regression test suite.
- test/baseline - The baseline results for the regression test suite.
2.2. 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 tar files, source code for third party libraries, and regression test baseline images.
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 a 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
For more details about using Git LFS, read our additional notes.
2.3. Accessing GitHub¶
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.
2.4. Cloning the Repository and Setting Up Hooks¶
You can access GitHub either through https or ssh. If you use 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.
To clone the repository:
git clone https://github.com/visit-dav/visit.git
git clone ssh://email@example.com/visit-dav/visit.git
To setup our hooks:
cd visit ./scripts/git-hooks/install-hooks.sh
2.5. Creating a Branch¶
Developement for VisIt is done off of two main branches, the
develop branch and the current release candidate branch, which was
3.2RC when this content was written. The
develop branch is used for development that will go into the next major or minor release. Major releases are releases where the first digit of the release number is incremented, Minor releases are releases where the second digit of the release number is incremented. The release candidate branch is used for development that will go into the next patch release. Patch releases are releases where the third digit of the release number is incremented.
There is no convention on the names of a branch. One commonly used convention is
Username is your GitHub user name,
YYYY is the current year,
MM is the current month,
DD is the current day, and
Description is a short description of the task to be performed. Since branches only exist while you are doing the development, the name isn’t critical, but it should be sufficiently descriptive so that someone can have some idea what the development on the branch is about.
To create a branch off of the
git checkout develop git pull git checkout -b task/user/2021_05_07_bug_fix
To create a branch off of the current release candidate:
git checkout 3.2RC git pull git checkout -b task/user/2021_05_07_bug_fix
2.6. Doing Development¶
Doing development using the Git version control system can be complex and take considerable time and effort to master. The primer below is just meant to get you started in modifying files and then pushing the changes to GitHub so that they can be integrated into VisIt.
To add a new file or modify an existing file, edit the file with your favorite text editor and then use the
add command so that git knows you want the file to be part of your next commit. To add a file:
git add src/myfile
To delete an existing file use the
git rm src/myfile
Once you have modified one or more files you can commit the change to git. You will typically do a commit after having modified one or more files that completes a logical unit of change. To commit the added files with a comment:
git commit -m "Description of my change."
It is recommended that you make commits frequently so that you can better track individual changes. The commit descriptions are typically brief. The record of the individual commits will not go into the final record of the commit, since we do “Squash and Merge” commits that merge all the commits into a single commit at GitHub. The individual commits will be helpful to you as a developer if you need to go back and understand when making many changes over a period of time. It may also potentially make it easier for reviewers to understand your commits.
Once you have finished all your changes you can push the change to GitHub. To push your changes to GitHub:
git push --set-upstream origin task/user/2021_05_07_bug_fix
Once you have pushed your changes to GitHub, you can submit a pull request.