ParaView Development Workflow

UNDER CONSTRUCTION

ParaView Development Workflow

ParaView uses a development workflow that incorporates elements from gitworkflows and integrates the ParaView Bug tracker into the process for documenting and tracking changes. There are occasional exceptions to this workflow, but those are strongly discouraged.

This document is not meant to be an exhaustive documentation of the process, but to give users and developers an overview of the process.

This document assumes you have your development environment is set using the default SetupForDevelopment.sh scripts provided under ParaView/Utiltiies/SetupForDevelopment.sh and ParaView/VTK/Utilities/SetupForDevelpoment.sh.

Integration Branches

Before we delve into the details, one must get acquainted with the various branches published on the official ParaView git repository.

• 'master' :- tracks commits that will become the next stable release of ParaView
• 'next' :- is intended as a testing branch where topics are merged for testing before they are merged into the 'master' through the gatekeeper review.

ParaView uses git submodules for various projects it depends on including VTK, QtTesting, etc. Among the submodules, the most important one is the VTK submodule.

The official VTK git repository has just one relevant branch:

• 'master' :- tracks commits that will become the next stable release of VTK.

To give ParaView some measure of isolation from changes happening in VTK and provide a mechanism for tracking updates from VTK being brought into ParaView, ParaView uses a couple of separate integration branches:

• 'pv-master' - VTK commits referenced by ParaView 'master'
• 'pv-next' - VTK commits referenced by ParaView 'next'.

Both these branches are accessible from the remote named 'pvvtk'.

One must note that no change is merged into pv-master unless it's already reachable in VTK master. This keeps pv-master from diverging from VTK master. 'pv-master' is always merged into VTK master ensuring topics started from pv-master or VTK master can be merged into each other without any issues.

To bring in topics into ParaView or PVVTK, one uses the stage.

Identify Changes

As a general rule, you should try to identify the changes you are planning to make before you start working on those. The change could be to fix a bug or to add a new feature. In any case, one reports the same an issue on the ParaView Bug Tracker (http://paraview.org/Bug).

Reporting a bug

When reporting a bug, users generally only need to specify the following fields:

1. Issue Found in Version: The version of ParaView in which the bug was detected. For feature requests, this field can be left empty.
2. Summary: A brief summary for the bug/feature.
3. Description: Details for the bug/feature. In case of bugs, report the means to reproduce the issue. This makes it easier to test that the bug has been fixed, or that it doesn't get reintroduced. In case of features, it's generally useful to document the use-case for the feature rather than the implementation itself since use-case can be tested easily, implementation details cannot.
4. Type: Classify the issue based on whether it's a feature request or a crash, etc. It's acceptable to simply pick the default value always.

Priority, Assign To and Project fields should not be set except unless explicitly told to by one of the ParaView team members.

Start a Topic

Once the bug has been reported, you can start working on resolving the bug. Once you've started working on the bug assign the bug to yourself and move the status to Active Development that way the team is aware that you are working on it and no one else will start working on it at the same time.

All changes to ParaView have to come through topic branches. A topic branch can start from any ancestor of the 'master' branch on ParaView git repository.

 # Start a new topic based on the master branch.
 > git checkout -b XXXX_fix_some_issue origin/master

Typically a branch is named using the issue number as the prefix.

With VTK Changes

ParaView includes VTK as a submodule. If you want to make changes to files under the VTK sub-directory, then you need to create another topic branch for the VTK submodule as well.

One can start a VTK topic on either vtk-master i.e. origin/master or pv-vtk/master or pv-master i.e. pvvtk/pv-master or any ancestor thereof.

 > cd VTK

 # Start a new VTK topic on master.
 > git checkout -b XXXX_fix_some_issue origin/master 
     OR
 > git checkout -b XXXX_fix_some_issue pv-vtk/master

 # Start a new VTK topic on pv-master.
 > git checkout -b XXXX_fix_some_issue pv-vtk/pv-master

pv-master is a branch parallel to VTK's master that ParaView refers to. The branch provides some isolation and control from the changes going into VTK.

One *SHOULD* name the VTK and ParaView topics using the same name. This greatly helps the gatekeeper review process described later.

Merge a Topic

Once you're satisfied with all your changes, the topic must be merged to the testing branch named next to have the changes tested on ParaView continuous (and some nightly) dashboards.

 # push the topic to ParaView stage
 > git stage-push

 # merge the topic into 'next'.
 > git stage-merge

If your topic has any VTK changes, then firstly, you need to ensure that there's at least one commit in your ParaView topic that refers to your VTK topic's head. Secondly, you need to push and merge VTK topic first before pushing and merging your ParaView topic.

 > cd VTK

 # push and merge VTK topic to pv-next
 > git pvvtk-push
 > git pvvtk-merge

Changes to VTK require an additional step. You need to get your changes approved by the VTK development community and merged into VTK using gerrit and then merged into VTK master for those changes to accepted during gatekeeper review. However, note that the VTK changes don't need have been reviewed and merged into VTK master for the above pvvtk-push and pvvtk-merge since that's only affecting the 'next' and 'pv-next' branches and not the master(s).

Once your VTK changes (if any) are in VTK master and ParaView changes tested on all dashboards safely, you should go back to the bug tracker and update the issue's status to "Gatekeeper Review". On the resolution page, one must set the Topic Name field as the name of the topic branch.

Only topics that are merged into next without causing any dashboard failures that have the corresponding issue on the bug tracker marked for 'Gatekeeper Review' will be considered for merging into the ParaView master which eventually becomes the next stable release of ParaView. Hence it's essential to have the Topic Name field for an issue set correctly when resolving the issue on the bug tracker.

Gatekeeper Review

Once a week a few members of the ParaView development team get together for what we call Gatekeeper Review Meetings. The goal of these meetings is to identify topics that have been merged into ParaView 'next' that are ready to be merged into 'master' and merge them.

The meeting proceeds by locating issues on the ParaView Bug Tracker that are in the 'Gatekeeper Review' state, then identifying the topics they refer to and verifying that they have been merged into 'next' and are not causing any dashboard failures. These topics are then merged into ParaView 'master' (and PVVTK pv-master, if applicable). The issues on the bug tracker are then moved to 'Customer Review' state at which point the reporter (or the customer) can verify that bug is fixed in master and close the issue.