Contributing to VTK-m

Note: These instructions are superseded by those at https://gitlab.kitware.com/vtk/vtk-m/blob/master/CONTRIBUTING.md

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

The VTK-m repository is set up such that you cannot push directly to it. Instead, it is placed in a shared repository for a review cycle.

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 is a merge request on the gitlab project.

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 gitlab. 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 gitlab git@gitlab.kitware.com:username/vtk-m.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 gitlab 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 gitlab
git checkout --track gitlab/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, you can share the work with the vtk-m community bey creating a merge request

To create a Merge request visit your fork in GitLab, browse to the "Merge Requests" link on the left, and use the "New Merge Request" button in the upper right to reach the URL:

https://gitlab.kitware.com/<username>/vtk-m/merge_requests/new

Follow these steps:

1. In the "Source branch" box select the <username>/vtk-m repository and the my-topic branch.
2. In the "Target branch" box select the vtk-m/vtk-m repository and the master branch. It should be the default. If your change is a fix for the release branch, you should still select the master branch as the target because the change needs to end up there too.
3. Use the "Compare branches" button to proceed to the next page and fill out the merge request creation form.
4. In the "Title" field provide a one-line summary of the entire topic. This will become the title of the Merge Request. Example Merge Request Title: Filter: Add Translate Filter
5. In the "Description" field provide a high-level description of the change the topic makes and any relevant information about how to try it.
   • Use @username syntax to draw attention of specific developers. This syntax may be used anywhere outside literal text and code blocks. Or, wait until the review stage and add comments to draw attention of developers.
6. Example Merge Request Description: This branch introduces a data set filter for the translate worklet.Cc: @user1 @user2
7. The "Assign to", "Milestone", and "Labels" fields may be left blank.
8. Use the "Submit merge request" button to create the merge request and visit its page.

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. If you are an authorized developer you may add a comment of the form

Do: merge

to ask that the change be merged into the upstream repository. By convention, do not request a merge if anybody has any open issues with the topic. If you are not an authorized developer please request in the Merge Request for an authorized developer to merge the branch.