Contributing to VTK-m

VTK-m development uses a git branchy workflow. This allows the core developers to contribute directly to VTK-m while still maintaining integrity in the code base. It also provides a convenient mechanism for developers outside of the core development team to make contributions to VTK-m. Both types of developers should follow the branchy workflow described here.

Branchy workflow includes the following steps, with more details further below.

1. Clone and build the source
2. Start a topic branch
3. Do development
4. Share and review
5. Merge to master

All VTK-m developers should also be on the VTK-m mailing list. Got to http://vtk.org/mailman/listinfo/vtkm to subscribe to the list.

Clone and build the source

A developer clones and builds the source just like any other developer. This process is documented on the [Building VTK-m] page.

Note that core developers that wish to push their own code will need to establish a public SSH key and use the SSH git protocol.

Start a topic branch

Before starting code for any topic or feature (no mater how trivial), create a "topic branch."

Usually a topic branch will be a branch of the master branch, but it is also possible to branch off other topic branches. Note, however, that if you branch off another topic branch, you are committed to the changes in that branch.

git checkout master
git pull
git checkout -b my-topic-name

Do Development

Develop on the branch as you would with any git workflow. That is, make changes, add the changes, and commit them when ready.

git add .
git commit

Note that when writing code for VTK-m, you need to follow the coding conventions outlined in the VTK-m Users' Guide.

Share and review

This step is optional for very small or trivial changes (such as changing a comment, fixing a compiler warning, or making changes to testing). However, for any significant change the new commits should be shared with one or more other core developers and reviewed.

Sharing the changes

There are multiple ways in git to share commits without modifying the master branch. One way is to use the git format-patch and email the commits. However, a more functional way of sharing is to push the topic branch to a publicly visible repository.

The first step of course is to create a public repository. The easiest way to do this is to fork the VTK-m repository on github. Once you do that you can add a reference to that repository from your local git repository. The command would look something like this.

git remote add my-repo git@github.com:username/vtkm.git

Once your publicly accessible remote repository is ready, you can push your topic branch to it. You can use a command like this:

git push --set-upstream my-repo HEAD

Note that the --set-upstream argument is optional. This sets up tracking for your topic branch. This means that if you make a change to your topic branch, you can push it to this same repository with a simple git push command. Likewise, if a change is made to the remote branch, you can get those changes with a simple git pull command. (Personally, I have a hard time remembering this command, so I have set up a git alias for it.)

We should stop and note that this is a great way to share with yourself. For example, you can use this branch on a remote repository to easily transfer your work between your desktop and your laptop. Let us say you issued that last push command on your desktop. On your laptop, add the remote to an existing git directory with the add remote command and issue commands like the following:

git fetch my-repo
git checkout --track my-repo/my-topic-name

As before, the --track command is not strictly necessary, but sets up the tracking for future pushes and pulls.

Reviewing the changes

Once the commits on the topic branch are publicly available, one or more core developers should look at it. You can use the VTK-m mailing list to ask for help. If you have pushed to a public repository, be sure to give the repository location and branch name.

Merge to master

When everyone agrees the code is ready to be contributed, it should be merged to master.

Not everyone has "push access" to the main VTK-m repository. Those that do not will have to ask a core developer to merge and push changes for them. Since you have already shared the changes for a review, this should not be an issue.

Those that do have push access to the main VTK-m repository can merge and push with the following steps.

git checkout master
git pull
git merge --no-ff my-topic-name
git push

Note that the merge command may suffer from conflicts. These can be resolved during the merge or kicked back to the original developer to resolve them by merging or rebasing the topic branch with the master branch.

Also note the --no-ff argument to the merge command. This option is important so please always use it. This option preserves the loops in the git history so that we have a record of all topics committed to the git repository. It also structures the git history to allow tricks like summarizing the development based on topic by using commands like the following.

git log --first-parent