|
|
| Line 1: |
Line 1: |
| This page documents how to develop VTK through [http://git-scm.com Git].
| | The instructions previously available on this page have been superseded. See [https://gitlab.kitware.com/vtk/vtk/tree/master/Documentation/dev/git#README here]. |
| See our [[VTK/Git|table of contents]] for more information. If you would like to backport bug/compile fixes to the release-5.10 branch see [[VTK/Git/Develop_Release|these instructions]].
| |
| | |
| <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 VTK 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://git-scm.com/book/ ProGit Book].
| |
| </i>
| |
| | |
| ==Setup==
| |
| | |
| Before you begin, perform initial setup:
| |
| | |
| {| style="width: 100%" cellspacing="0" cellpadding="0"
| |
| |-
| |
| |width=60%|
| |
| 1.
| |
| Register [[VTK/Git/Account#Gerrit|Gerrit access]].
| |
| |-
| |
| |
| |
| 2.
| |
| Follow the [[VTK/Git/Download#Clone|download instructions]] to create a local VTK clone:
| |
| |-
| |
| |
| |
| :<code>$ git clone git://vtk.org/VTK.git</code>
| |
| |align="center"|
| |
| [[Git/Trouble#Firewall_Blocks_Port_9418|Connection refused]]?
| |
| |-
| |
| |
| |
| 3.
| |
| Run the developer setup script to prepare your VTK work tree and create Git command aliases used below:
| |
| |-
| |
| |
| |
| :<code>$ ./Utilities/SetupForDevelopment.sh</code>
| |
| |align="center"|
| |
| [http://vtk.org/gitweb?p=VTK.git;a=blob;f=Utilities/SetupForDevelopment.sh;hb=HEAD <code>SetupForDevelopment.sh</code>]
| |
| <br/>
| |
| [http://git-scm.com/book/en/Getting-Started-First-Time-Git-Setup Pro Git: Setup]
| |
| |-
| |
| |
| |
| 4. (Optional but highly recommended.)
| |
| Register with the VTK project on Kitware's CDash instance to better know how your code performs in regression tests.
| |
| |-
| |
| |Go to https://open.cdash.org/register.php and enter your name and email address.
| |
| After registering and signing in, click on "All Dashboards" link in the upper left corner,
| |
| scroll down and click "Subscribe to this project" on the right of VTK.
| |
| |}
| |
| | |
| ==Workflow==
| |
| | |
| VTK development uses a [[Git/Workflow/Topic|branchy workflow]] based on topic branches.
| |
| 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.
| |
| Code Review
| |
| |-
| |
| |
| |
| :* [[#Share_a_Topic|Share a Topic]] (requires [[VTK/Git/Account#Gerrit|Gerrit access]])
| |
| |align="center"|
| |
| [http://code.google.com/p/gerrit/ Gerrit Code Review]
| |
| |-
| |
| |
| |
| :* [[#Revise_a_Topic|Revise a Topic]]
| |
| |-
| |
| |
| |
| 3.
| |
| Integrate Changes
| |
| |-
| |
| |
| |
| :* [[#Merge_a_Topic|Merge a Topic]] (requires permission in Gerrit)
| |
| |-
| |
| |
| |
| :* [[#Delete_a_Topic|Delete a Topic]]
| |
| |}
| |
| | |
| ==Update==
| |
| | |
| {| style="width: 100%"
| |
| |-
| |
| |width=60%|
| |
| Update your local '''master''' branch:
| |
| |-
| |
| |
| |
| :<code>$ git checkout master</code>
| |
| :<code>$ git pull</code>
| |
| |align="center"|
| |
| [http://schacon.github.com/git/git-checkout.html <code>git help checkout</code>]
| |
| <br/>
| |
| [http://schacon.github.com/git/git-pull.html <code>git help pull</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>
| |
| :{|
| |
| |-
| |
| |
| |
| For new development, start the topic from <code>origin/master</code>:
| |
| :<code>$ git checkout -b ''my-topic'' origin/master</code>
| |
| |-
| |
| |
| |
| For release branch fixes, start the topic from <code>origin/release</code>, and by convention use a topic name starting in "<code>release-</code>":
| |
| :<code>$ git checkout -b ''my-topic'' origin/release</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://git-scm.com/book/en/Git-Branching-Basic-Branching-and-Merging Pro Git: Basic Branching]
| |
| |-
| |
| |
| |
| Edit files and create commits (repeat as needed):
| |
| |-
| |
| |
| |
| :<code>$ edit ''file1'' ''file2'' ''file3''</code>
| |
| :''(To add data follow [[VTK/Git/Develop/Data#Add_Data|these instructions]].)''
| |
| :<code>$ git add ''file1'' ''file2'' ''file3''</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://git-scm.com/book/en/Git-Basics-Recording-Changes-to-the-Repository Pro Git: Recording Changes]
| |
| |-
| |
| |
| |
| ''(If your change modifies the "<code>Utilities/KWSys/vtksys</code>" directory please contribute directly to [[KWSys/Git|KWSys]] instead.)''
| |
| ''(If your change modifies the "<code>Utilities/MetaIO/vtkmetaio</code>" directory please contribute directly to [https://github.com/Kitware/metaio MetaIO] instead.)''
| |
| |}
| |
| | |
| ==Share a Topic==
| |
| | |
| When a topic is ready for review and possible inclusion, share it by pushing to Gerrit.
| |
| Be sure you have registered for [[VTK/Git/Account#Gerrit|Gerrit 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 Gerrit for review:
| |
| |-
| |
| |
| |
| :<code>$ git prepush</code>
| |
| |align="center"|
| |
| [http://vtk.org/gitweb?p=VTK.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 for review by the community:
| |
| |-
| |
| |
| |
| :<code>$ git gerrit-push</code>
| |
| :''(If the topic adds data see [[VTK/Git/Develop/Data#Push|this note]].)''
| |
| The output will include a link to the topic review page in [http://review.source.kitware.com/p/VTK VTK Gerrit].
| |
| |align="center"|
| |
| [http://vtk.org/gitweb?p=VTK.git;a=blob;f=Utilities/Scripts/SetupGitAliases.sh;hb=HEAD <code>alias.gerrit-push</code>]
| |
| |-
| |
| |
| |
| Find your topic/change in the [http://review.source.kitware.com/p/VTK VTK Gerrit] instance and add reviewers.
| |
| Add at least one relevant member of the [http://review.source.kitware.com/#/admin/groups/11,members VTK-core Group] who will have permission to approve the topic for submission. They will need to go to the last change set in the topic and request a dashboard submission. This is
| |
| done by clicking on the Review button and entering "request build" into the cover message.
| |
| | |
| The "Kitware Robot" automatically performs basic checks on the commits and adds a review that sets the "Verified" flag.
| |
| |align="center"|
| |
| [[File:AddReviewer.png]]
| |
| |}
| |
| | |
| ==Revise a Topic==
| |
| | |
| If a topic is approved during Gerrit review, skip to the [[#Merge_a_Topic|next step]].
| |
| Otherwise, revise the topic and push it back to Gerrit for another review.
| |
| | |
| {| 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>]
| |
| |-
| |
| |
| |
| To revise the <code>3</code>rd commit back on the topic:
| |
| |-
| |
| |
| |
| :<code>$ git rebase -i HEAD~3</code>
| |
| ''(Substitute the correct number of commits back, as low as ''<code>1</code>''.)''
| |
| | |
| Follow Git's interactive instructions.
| |
| Preserve the <code>Change-Id:</code> line at the bottom of each commit message.
| |
| |align="center"|
| |
| [http://schacon.github.com/git/git-rebase.html <code>git help rebase</code>]
| |
| <br/>
| |
| [http://git-scm.com/book/en/Git-Branching-Rebasing Pro Git: Rebasing]
| |
| |-
| |
| |
| |
| Return to the [[#Share_a_Topic|previous step]] to share the revised topic.
| |
| |}
| |
| | |
| ==Merge a Topic==
| |
| | |
| After a topic has been reviewed and approved in Gerrit, merge it into the upstream repository.
| |
| | |
| {| style="width: 100%"
| |
| |-
| |
| |width=60%|
| |
| Visit the [http://review.source.kitware.com/p/VTK VTK Gerrit] review page for your topic.
| |
| Members of the [http://review.source.kitware.com/#/admin/groups/11,members VTK-core Group] may use the "Submit Change Set" button to merge the topic, as pictured on the right.
| |
| Non-members will not see the button but if the topic has been approved then at least one reviewer is a member of VTK-core and may be asked to perform the submission.
| |
| |align="center"|
| |
| [[File:SubmitChangeSet1.png]]
| |
| |-
| |
| |
| |
| If the submission is rejected by a merge conflict, fetch the latest upstream history and rebase on it:
| |
| |-
| |
| |
| |
| :<code>$ git fetch origin</code>
| |
| :<code>$ git rebase origin/master</code>
| |
| :''(If you are fixing a bug in the latest release then substitute'' <code>origin/release</code> ''for'' <code>origin/master</code>''.)''
| |
| |align="center"|
| |
| [http://schacon.github.com/git/git-fetch.html <code>git help fetch</code>]
| |
| <br/>
| |
| [http://schacon.github.com/git/git-rebase.html <code>git help rebase</code>]
| |
| <br/>
| |
| [http://git-scm.com/book/en/Git-Branching-Rebasing Pro Git: Rebasing]
| |
| |-
| |
| |
| |
| Preserve the <code>Change-Id:</code> line at the bottom of each commit message.
| |
| |-
| |
| |
| |
| Return to the [[#Share_a_Topic|above step]] to share the revised topic.
| |
| |}
| |
| | |
| ==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 pull</code>
| |
| |align="center"|
| |
| [http://schacon.github.com/git/git-checkout.html <code>git help checkout</code>]
| |
| <br/>
| |
| [http://schacon.github.com/git/git-pull.html <code>git help pull</code>]
| |
| |-
| |
| |
| |
| Delete the local topic branch:
| |
| |-
| |
| |
| |
| :<code>$ git branch -d ''my-topic''</code>
| |
| |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).
| |
| |}
| |
