|
|
| (21 intermediate revisions by 2 users not shown) |
| Line 1: |
Line 1: |
| __NOTOC__
| | The instructions previously available on this page have been superseded. See [https://gitlab.kitware.com/paraview/paraview/blob/master/Documentation/dev/git/develop.md here]. |
| | |
| This page documents how to develop ParaView through [http://git-scm.com Git].
| |
| See our [[ParaView/Git|table of contents]] for more information.
| |
| | |
| <i>
| |
| Git is an extremely powerful version control tool that supports many different "workflows" for indivudal development and collaboration.
| |
| Here we document procedures used by the ParaView development community.
| |
| In the interest of simplicity and brevity we do '''not''' provide an explanation of why we use this approach.
| |
| Furthermore, this is '''not''' a Git tutorial.
| |
| Please see our [[Git/Resources|Git resource links]] for third-party documentation, such as the [http://progit.org/book/ ProGit Book].
| |
| </i>
| |
| | |
| ==Target Audience==
| |
| | |
| This document is intended for developers from the larger ParaView open-source community who want to contribute patches back to ParaView. Registered developers of ParaView (with write access to the git repository) should refer to [http://www.paraview.org/ParaView3/index.php/ParaView_Development_Workflow ParaView Developers Wiki] for instructions on using the ParaView integration branches for contributing code. The rest of the community can push contributions to ParaView using the workflow described here.
| |
| | |
| ==Setup==
| |
| | |
| Before you begin, perform initial setup:
| |
| | |
| {| style="width: 100%" cellspacing="0" cellpadding="0"
| |
| |-
| |
| |width=60%|
| |
| 1.
| |
| Register [[ParaView/Git/Account#Gerrit|Gerrit access]].
| |
| |-
| |
| |
| |
| 2.
| |
| Follow the [[ParaView/Git/Download#Clone|download instructions]] to create a local ParaView clone:
| |
| |-
| |
| |
| |
| :<code>$ git clone --recursive git://paraview.org/ParaView.git</code>
| |
| |align="center"|
| |
| [[Git/Trouble#Firewall_Blocks_Port_9418|Connection refused]]?
| |
| |-
| |
| |
| |
| 3.
| |
| Run the developer setup script to prepare your ParaView work tree and create Git command aliases used below:
| |
| |-
| |
| |
| |
| :<code>$ ./Utilities/SetupForDevelopment.sh</code>
| |
| |align="center"|
| |
| [http://paraview.org/gitweb?p=ParaView.git;a=blob;f=Utilities/SetupForDevelopment.sh;hb=HEAD <code>SetupForDevelopment.sh</code>]
| |
| <br/>
| |
| [http://progit.org/book/ch1-5.html Pro Git: Setup]
| |
| |}
| |
| | |
| ==Workflow==
| |
| | |
| ParaView development uses a [[Git/Workflow/Topic|branchy workflow]] based on topic branches.
| |
| We manage changes to the VTK submodule using an [[ParaView/Git/Develop/PVVTK#Workflow|extended VTK workflow]].
| |
| 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 your local '''master''' branch:
| |
| |-
| |
| |
| |
| :<code>$ git checkout master</code>
| |
| :<code>$ git pullall</code>
| |
| |align="center"|
| |
| [http://schacon.github.com/git/git-checkout.html <code>git help checkout</code>]
| |
| <br/>
| |
| [http://paraview.org/gitweb?p=ParaView.git;a=blob;f=Utilities/Scripts/SetupGitAliases.sh;hb=HEAD <code>alias.pullall</code>]
| |
| <br/>
| |
| ([http://schacon.github.com/git/git-pull.html <code>pull</code>] and
| |
| [http://schacon.github.com/git/git-submodule.html <code>submodule</code>] <code>update</code>)
| |
| |}
| |
| | |
| ==Create a Topic==
| |
| | |
| All new work must be committed on topic branches.
| |
| Name topics like you might name functions: concise but precise.
| |
| A reader should have a general idea of the feature or fix to be developed given just the branch name.
| |
| | |
| {| style="width: 100%"
| |
| |-
| |
| |width=60%|
| |
| To start a new topic branch:
| |
| |-
| |
| |
| |
| :<code>$ git fetch origin</code>
| |
| :<code>$ git checkout -b ''my-topic'' origin/master</code>
| |
| :''(If you are fixing a bug in the latest release then substitute'' <code>origin/release</code> ''for'' <code>origin/master</code>''.<br/>Then run'' <code>git submodule update</code>''.)''
| |
| |align="center"|
| |
| [http://schacon.github.com/git/git-fetch.html <code>git help fetch</code>]
| |
| <br/>
| |
| [http://schacon.github.com/git/git-checkout.html <code>git help checkout</code>]
| |
| <br/>
| |
| [http://schacon.github.com/git/git-submodule.html <code>git help submodule</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>
| |
| :''(To change VTK [[ParaView/Git/Develop/PVVTK#Create_a_Topic|create a VTK topic]] and use <code>git add VTK</code>.)''
| |
| :<code>$ git commit</code>
| |
| |align="center"|
| |
| [http://schacon.github.com/git/git-add.html <code>git help add</code>]
| |
| <br/>
| |
| [http://schacon.github.com/git/git-commit.html <code>git help commit</code>]
| |
| <br/>
| |
| [http://progit.org/book/ch2-2.html Pro Git: Recording Changes]
| |
| |}
| |
| | |
| ==Share a Topic==
| |
| | |
| When a topic is ready for testing and review by others, share it by pushing it to the topic stage.
| |
| Be sure you have registered for [[ParaView/Git/Account#Git|Git push access]].
| |
| | |
| {| style="width: 100%"
| |
| |-
| |
| |width=60%|
| |
| Checkout the topic if it is not your current branch:
| |
| |-
| |
| |
| |
| :<code>$ git checkout ''my-topic''</code>
| |
| |align="center"|
| |
| [http://schacon.github.com/git/git-checkout.html <code>git help checkout</code>]
| |
| |-
| |
| |
| |
| Check what commits will be pushed to the topic stage:
| |
| |-
| |
| |
| |
| :<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://schacon.github.com/git/git-log.html <code>log</code>] <code>origin/master..</code>)
| |
| |-
| |
| |
| |
| Push commits in your topic branch to the topic stage:
| |
| |-
| |
| |
| |
| :''(If you changed VTK [[ParaView/Git/Develop/PVVTK#Share_a_Topic|share the VTK topic]] first.)''
| |
| :<code>$ git stage-push</code>
| |
| |align="center"|
| |
| [http://paraview.org/gitweb?p=ParaView.git;a=blob;f=Utilities/Scripts/SetupGitAliases.sh;hb=HEAD <code>alias.stage-push</code>]
| |
| <br/>
| |
| ([http://schacon.github.com/git/git-push.html <code>push</code>] <code>stage HEAD</code>)
| |
| |}
| |
| | |
| The topic is now published on the [http://paraview.org/stage/ParaView.git ParaView Topic Stage] and may be (optionally) reviewed by others.
| |
| | |
| ==Merge a Topic for Testing==
| |
| | |
| When your topic is ready, merge it to the ParaView '''next''' branch for testing.
| |
| | |
| {| style="width: 100%"
| |
| |-
| |
| |width=60%|
| |
| Checkout the topic if it is not your current branch:
| |
| |-
| |
| |
| |
| :<code>$ git checkout ''my-topic''</code>
| |
| |align="center"|
| |
| [http://schacon.github.com/git/git-checkout.html <code>git help checkout</code>]
| |
| |-
| |
| |
| |
| Ask the topic stage to automatically merge the topic.
| |
| It will merge to '''next''' by default.
| |
| |-
| |
| |
| |
| :''(If you changed VTK [[ParaView/Git/Develop/PVVTK#Merge_a_Topic_for_Testing|merge the VTK topic]] first.)''
| |
| :<code>$ git stage-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.stage-merge</code>]
| |
| <br/>
| |
| (<code>ssh git@paraview.org stage ParaView merge ''my-topic''</code>)
| |
| <br/>
| |
| [[Git/Workflow/Topic/Conflicts#Topic-to-Topic|Topic-to-Topic Conflict Resolution]]
| |
| |}
| |
| | |
| The topic is now integrated into ParaView's '''next''' branch and will be tested by dashboard builds.
| |
| | |
| ==Extend a Topic==
| |
| | |
| If your topic runs cleanly after a night of dashboard builds, it is ready for the [[#Merge_a_Topic_for_Inclusion|next step]].
| |
| 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>
| |
| :<code>$ git submodule update</code>
| |
| |align="center"|
| |
| [http://schacon.github.com/git/git-checkout.html <code>git help checkout</code>]
| |
| <br/>
| |
| [http://schacon.github.com/git/git-submodule.html <code>git help submodule</code>]
| |
| |-
| |
| |
| |
| Edit files and create commits (repeat as needed):
| |
| |-
| |
| |
| |
| :<code>$ edit ''file1'' ''file2'' ''file3''</code>
| |
| :<code>$ git add ''file1'' ''file2'' ''file3''</code>
| |
| :''(To fix VTK [[ParaView/Git/Develop/PVVTK#Extend_a_Topic|extend the VTK topic]] and use <code>git add VTK</code>.)''
| |
| :<code>$ git commit</code>
| |
| |align="center"|
| |
| [http://schacon.github.com/git/git-add.html <code>git help add</code>]
| |
| <br/>
| |
| [http://schacon.github.com/git/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==
| |
| | |
| Only core maintainers have access to merge a topic to '''master'''.
| |
| They meet weekly to evaluate topics in '''next''' ([[ParaView/Git/Develop/PVVTK#Merge_a_Topic_for_Inclusion|and PVVTK '''pv-next''']]) based on dashboard results and manual review.
| |
| If your topic is accepted it will be merged to '''master''' for permanent inclusion after which you may [[#Delete_a_Topic|delete it]].
| |
| 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 a topic has been merged upstream, delete your local branch for the topic.
| |
| | |
| {| style="width: 100%"
| |
| |-
| |
| |width=60%|
| |
| Checkout and update the '''master''' branch:
| |
| |-
| |
| |
| |
| :<code>$ git checkout master</code>
| |
| :<code>$ git pullall</code>
| |
| |align="center"|
| |
| [http://schacon.github.com/git/git-checkout.html <code>git help checkout</code>]
| |
| <br/>
| |
| [http://paraview.org/gitweb?p=ParaView.git;a=blob;f=Utilities/Scripts/SetupGitAliases.sh;hb=HEAD <code>alias.pullall</code>]
| |
| <br/>
| |
| ([http://schacon.github.com/git/git-pull.html <code>pull</code>] and
| |
| [http://schacon.github.com/git/git-submodule.html <code>submodule</code>] <code>update</code>)
| |
| |-
| |
| |
| |
| Delete the local topic branch:
| |
| |-
| |
| |
| |
| :<code>$ git branch -d ''my-topic''</code>
| |
| :''(If you changed VTK [[ParaView/Git/Develop/PVVTK#Delete_a_Topic|delete the VTK topic]].)''
| |
| |align="center"|
| |
| [http://schacon.github.com/git/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).
| |
| |}
| |
