|
|
| Line 1: |
Line 1: |
| __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).
| |
| |}
| |
