|
|
| Line 1: |
Line 1: |
| __NOTOC__
| | The instructions previously available on this page have been superseded. See [https://gitlab.kitware.com/utils/kwsys/blob/master/CONTRIBUTING.rst here]. |
| | |
| This page documents how to develop KWSys through [http://git-scm.com Git].
| |
| See our [[KWSys/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 KWSys 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 [[KWSys/Git/Account#Gerrit|Gerrit access]].
| |
| |-
| |
| |
| |
| 2.
| |
| Follow the [[KWSys/Git/Download#Clone|download instructions]] to create a local KWSys clone:
| |
| |-
| |
| |
| |
| :<code>$ git clone git://public.kitware.com/KWSys.git</code>
| |
| |align="center"|
| |
| [[Git/Trouble#Firewall_Blocks_Port_9418|Connection refused]]?
| |
| |-
| |
| |
| |
| 3.
| |
| Run the developer setup script to prepare your KWSys work tree and create Git command aliases used below:
| |
| |-
| |
| |
| |
| :<code>$ ./SetupForDevelopment.sh</code>
| |
| |align="center"|
| |
| [http://public.kitware.com/gitweb?p=KWSys.git;a=blob;f=SetupForDevelopment.sh;hb=HEAD <code>SetupForDevelopment.sh</code>]
| |
| <br/>
| |
| [http://git-scm.com/book/en/Getting-Started-First-Time-Git-Setup Pro Git: Setup]
| |
| |}
| |
| | |
| ==Workflow==
| |
| | |
| KWSys 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 [[KWSys/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>
| |
| :<code>$ git checkout -b ''my-topic'' 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-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>
| |
| :<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]
| |
| |}
| |
| | |
| ==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 [[KWSys/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://public.kitware.com/gitweb?p=KWSys.git;a=blob;f=GitSetup/setup-aliases;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>
| |
| The output will include a link to the change review page in [http://review.source.kitware.com/p/KWSys KWSys Gerrit].
| |
| |align="center"|
| |
| [http://public.kitware.com/gitweb?p=KWSys.git;a=blob;f=GitSetup/setup-aliases;hb=HEAD <code>alias.gerrit-push</code>]
| |
| |-
| |
| |
| |
| Find your change in the [http://review.source.kitware.com/p/KWSys KWSys Gerrit] instance and add reviewers.
| |
| Add at least one relevant member of the [http://review.source.kitware.com/#/admin/groups/34,members KWSys-core Group] who will have permission to approve the change for submission.
| |
| |align="center"|
| |
| [[File:AddReviewer.png]]
| |
| |-
| |
| |
| |
| The "Kitware Robot" automatically performs basic checks on the commits and adds a review that sets the "Verified" flag.
| |
| |-
| |
| |
| |
| '''KWSys is shared by multiple projects and therefore is [http://open.cdash.org/index.php?project=KWSys#Experimental tested on many platforms].'''
| |
| '''Proposed changes must work on all of the platforms before they will be approved even if the changes are motivated by a host project with fewer platforms.'''
| |
| |-
| |
| |
| |
| Authorized reviewers may add a "Testing: Enable" review comment to activate testing of the latest patch set.
| |
| Authors should visit the [http://open.cdash.org/index.php?project=KWSys#Experimental KWSys Dashboard] to look for build names starting in the topic name.
| |
| If any problems are reported proceed to the [[#Revise_a_Topic|next step]] to revise your change to address them.
| |
| |align="center"|
| |
| [http://open.cdash.org/index.php?project=KWSys#Experimental KWSys Dashboard]
| |
| |}
| |
| | |
| ==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/KWSys KWSys Gerrit] review page for your change.
| |
| Members of the [http://review.source.kitware.com/#/admin/groups/34,members KWSys-core Group] may use the "Submit Patch Set" button to merge the topic, as pictured on the right.
| |
| Non-members will not see the button but if the change has been approved then at least one reviewer is a member of KWSys-core and may be asked to perform the submission.
| |
| |align="center"|
| |
| [[File:SubmitPatchSet1.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>
| |
| |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).
| |
| |}
| |
