ParaView/Git/Develop/PVVTK

From KitwarePublic
< ParaView‎ | Git‎ | Develop
Revision as of 21:35, 8 June 2011 by Brad.king (talk | contribs) (Created page with "__NOTOC__ This page documents how to develop VTK inside ParaView through [http://git-scm.com Git]. See our table of contents for more information. ==Setup== T...")
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to navigationJump to search


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

2. Testing and Review

3. Integration by Maintainers

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 automatic merge fails due to conflicts follow the printed instructions to resolve them.)

alias.pvvtk-merge
(ssh git@paraview.org stage PVVTK merge my-topic)

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