View source for ParaView/Git/Develop/PVVTK

__NOTOC__

This page documents how to develop VTK inside ParaView through [http://git-scm.com Git].
See our [[ParaView/Git|table of contents]] for more information.

==Setup==

This page assumes you have set up development of ParaView as described [[ParaView/Git/Develop#Setup|here]].
Set the current working directory to VTK at the beginning of each set of commands below:
:<code>$ cd VTK</code>

==Workflow==

VTK development within ParaView uses a [[Git/Workflow/Topic|branchy workflow]] beyond that used for plain VTK development.
The [http://paraview.org/PVVTK.git 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:

{| style="width: 100%" cellspacing="0" cellpadding="0"
|-
|width=60%|
1.
Local Development
|-
|
:* [[#Update|Update]]
|-
|
:* [[#Create_a_Topic|Create a Topic]]
|-
|
2.
Testing and Review
|-
|
:* [[#Share_a_Topic|Share a Topic]]
|-
|
:* [[#Merge_a_Topic_for_Testing|Merge a Topic for Testing]]
|-
|
:* [[#Extend_a_Topic|Extend a Topic]]
|-
|
3.
Integration by Maintainers
|-
|
:* [[#Merge_a_Topic_for_Inclusion|Merge a Topic for Inclusion]]
|-
|
:* [[#Delete a Topic|Delete a Topic]]
|}

==Update==

{| style="width: 100%"
|-
|width=60%|
Update the VTK directory to the version referenced by the ParaView checkout.
|-
|
:<code>$ cd ..</code>
:<code>$ git submodule update VTK</code>
:<code>$ cd VTK</code>
|align="center"|
[http://www.kernel.org/pub/software/scm/git/docs/git-submodule.html <code>git help submodule</code>]
|}

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

{| style="width: 100%"
|-
|width=60%|
Start a new topic from the HEAD of VTK currently checked out by ParaView.
|-
|
:<code>$ git checkout -b ''my-topic''</code>
|align="center"|
[http://www.kernel.org/pub/software/scm/git/docs/git-checkout.html <code>git help checkout</code>]
<br/>
[http://progit.org/book/ch3-2.html Pro Git: Basic Branching]
|-
|
Edit files and create commits (repeat as needed):
|-
|
:<code>$ edit ''file1'' ''file2'' ''file3''</code>
:<code>$ git add ''file1'' ''file2'' ''file3''</code>
:<code>$ git commit</code>
|align="center"|
[http://www.kernel.org/pub/software/scm/git/docs/git-add.html <code>git help add</code>]
<br/>
[http://www.kernel.org/pub/software/scm/git/docs/git-commit.html <code>git help commit</code>]
<br/>
[http://progit.org/book/ch2-2.html Pro Git: Recording Changes]
|}

Return to [[ParaView/Git/Develop#Create_a_Topic|creating]] your ParaView topic.

==Share a Topic==

A VTK topic developed for ParaView must be shared with both communities simultaneously:
* Follow the [[VTK/Git/Simple|VTK development process]] for review in Gerrit.
* Follow the instructions below to share the topic for ParaView.
Be sure you have registered for [[ParaView/Git/Account#Git|Git push access]] to ParaView.

{| style="width: 100%"
|-
|width=60%|
Checkout the topic if it is not your current branch:
|-
|
:<code>$ git checkout ''my-topic''</code>
|align="center"|
[http://www.kernel.org/pub/software/scm/git/docs/git-checkout.html <code>git help checkout</code>]
|-
|
Check what commits will be pushed to PVVTK:
|-
|
:<code>$ git prepush</code>
|align="center"|
[http://paraview.org/gitweb?p=ParaView.git;a=blob;f=Utilities/Scripts/SetupGitAliases.sh;hb=HEAD <code>alias.prepush</code>]
<br/>
([http://www.kernel.org/pub/software/scm/git/docs/git-log.html <code>log</code>] <code>origin/master..</code>)
|-
|
Push commits in your topic branch to PVVTK:
|-
|
:<code>$ git pvvtk-push</code>
|align="center"|
[http://paraview.org/gitweb?p=ParaView.git;a=blob;f=Utilities/Scripts/SetupGitAliases.sh;hb=HEAD <code>alias.pvvtk-push</code>]
<br/>
([http://www.kernel.org/pub/software/scm/git/docs/git-push.html <code>push</code>] <code>pvvtk HEAD</code>)
|}

Return to [[ParaView/Git/Develop#Share_a_Topic|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'''.

{| style="width: 100%"
|-
|width=60%|
Checkout the topic if it is not your current branch:
|-
|
:<code>$ git checkout ''my-topic''</code>
|align="center"|
[http://www.kernel.org/pub/software/scm/git/docs/git-checkout.html <code>git help checkout</code>]
|-
|
Ask the PVVTK Topic Stage to automatically merge the topic.
It will merge to '''pv-next''' by default.
|-
|
:<code>$ git pvvtk-merge</code>
:''(If the merge conflicts follow the printed instructions to resolve them.)''
|align="center"|
[http://paraview.org/gitweb?p=ParaView.git;a=blob;f=Utilities/Scripts/SetupGitAliases.sh;hb=HEAD <code>alias.pvvtk-merge</code>]
<br/>
(<code>ssh git@paraview.org stage PVVTK merge ''my-topic''</code>)
<br/>
[[Git/Workflow/Topic/Conflicts#Branch-to-Topic|Branch-to-Topic Conflict Resolution]]
|}

Return to [[ParaView/Git/Develop#Merge_a_Topic_for_Testing|merging]] your ParaView topic.

==Extend a Topic==

The VTK topic is ready for the [[#Merge_a_Topic_for_Inclusion|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.

{| style="width: 100%"
|-
|width=60%|
Checkout the topic if it is not your current branch:
|-
|
:<code>$ git checkout ''my-topic''</code>
|align="center"|
[http://www.kernel.org/pub/software/scm/git/docs/git-checkout.html <code>git help checkout</code>]
|-
|
Edit files and create commits (repeat as needed):
|-
|
:<code>$ edit ''file1'' ''file2'' ''file3''</code>
:<code>$ git add ''file1'' ''file2'' ''file3''</code>
:<code>$ git commit</code>
|align="center"|
[http://www.kernel.org/pub/software/scm/git/docs/git-add.html <code>git help add</code>]
<br/>
[http://www.kernel.org/pub/software/scm/git/docs/git-commit.html <code>git help commit</code>]
<br/>
[http://progit.org/book/ch2-2.html Pro Git: Recording Changes]
|}

Return to the [[#Share_a_Topic|earlier step]] to share the extended topic.

==Merge a Topic for Inclusion==

Optionally follow the [[VTK/Git/Simple|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 [[#Extend_a_Topic|above step]] to address their concerns.

==Delete a Topic==

After the containing ParaView topic has been merged to ParaView '''master'''
[[ParaView/Git/Develop#Delete_a_Topic|delete the ParaView topic]] first.

{| style="width: 100%"
|-
|width=60%|
Then delete your local branch for the VTK topic:
|-
|
:<code>$ git branch -d ''my-topic''</code>
|align="center"|
[http://www.kernel.org/pub/software/scm/git/docs/git-branch.html <code>git help branch</code>]
|-
|
The <code>branch -d</code> command works only when the topic branch has been correctly merged.
Use <code>-D</code> instead of <code>-d</code> to force the deletion of an unmerged topic branch
(warning - you could lose commits).
|}