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