ParaView/Git/Develop/PVVTK

This page documents how to develop VTK inside ParaView through Git. See our table of contents for more information.

Setup

This page assumes you have set up development of ParaView as described here. Set the current working directory to VTK at the beginning of each set of commands below:

$ cd VTK

Workflow

VTK development within ParaView uses a branchy workflow beyond that used for plain VTK development. The PVVTK Topic Stage defines two integration branches:

• pv-master: VTK commits referenced by ParaView master
• pv-next: VTK commits referenced by ParaView next

The PVVTK pv-master branch is always contained by the VTK master branch, but not vice-versa.

Our collaboration workflow consists of three main steps:

1. Local Development

Update

Create a Topic

2. Testing and Review

Share a Topic

Merge a Topic for Testing

Extend a Topic

3. Integration by Maintainers

Merge a Topic for Inclusion

Delete a Topic

Update

Update the VTK directory to the version referenced by the ParaView checkout.
$ cd .. $ git submodule update VTK $ cd VTK	git help submodule

Create a Topic

VTK changes needed during development of a ParaView topic must be made on a VTK topic. The two topics may or may not have the same name.

Start a new topic from the HEAD of VTK currently checked out by ParaView.
$ git checkout -b my-topic	git help checkout Pro Git: Basic Branching
Edit files and create commits (repeat as needed):
$ edit file1 file2 file3 $ git add file1 file2 file3 $ git commit	git help add git help commit Pro Git: Recording Changes

Return to creating your ParaView topic.

Share a Topic

A VTK topic developed for ParaView must be shared with both communities simultaneously:

• Follow the VTK development process for review in Gerrit.
• Follow the instructions below to share the topic for ParaView.

Be sure you have registered for Git push access to ParaView.

Checkout the topic if it is not your current branch:
$ git checkout my-topic	git help checkout
Check what commits will be pushed to PVVTK:
$ git prepush	alias.prepush (log origin/master..)
Push commits in your topic branch to PVVTK:
$ git pvvtk-push	alias.pvvtk-push (push pvvtk HEAD)

Return to sharing your ParaView topic.

Merge a Topic for Testing

When your topic is ready merge it to PVVTK pv-next to allow the containing ParaView topic to be merged to ParaView next.

Checkout the topic if it is not your current branch:
$ git checkout my-topic	git help checkout
Ask the PVVTK Topic Stage to automatically merge the topic. It will merge to pv-next by default.
$ git pvvtk-merge (If the merge conflicts follow the printed instructions to resolve them.)	alias.pvvtk-merge (ssh git@paraview.org stage PVVTK merge my-topic) Branch-to-Topic Conflict Resolution

Return to merging your ParaView topic.

Extend a Topic

The VTK topic is ready for the next step if

• it has been approved by the VTK development process (Gerrit review), and
• the containing ParaView topic merges to ParaView next cleanly, and
• the containing ParaView topic runs correctly on the dashboard.

Otherwise, extend the topic with additional commits to fix the problems.

Checkout the topic if it is not your current branch:
$ git checkout my-topic	git help checkout
Edit files and create commits (repeat as needed):
$ edit file1 file2 file3 $ git add file1 file2 file3 $ git commit	git help add git help commit Pro Git: Recording Changes

Return to the earlier step to share the extended topic.

Merge a Topic for Inclusion

Optionally follow the VTK development process to merge the topic to VTK master but note that the rest of this step must be followed before the topic can be used in ParaView.

Only core maintainers have access to merge a topic to PVVTK pv-master. They meet weekly to evaluate topics in pv-next based on dashboard results and manual review. If your topic is accepted it will be merged to pv-master to allow its use in ParaView master. Otherwise the maintainers will contact you with feedback. Respond by returning to the above step to address their concerns.

Delete a Topic

After the containing ParaView topic has been merged to ParaView master delete the ParaView topic first.

Then delete your local branch for the VTK topic:
$ git branch -d my-topic	git help branch
The branch -d command works only when the topic branch has been correctly merged. Use -D instead of -d to force the deletion of an unmerged topic branch (warning - you could lose commits).