CMake/Git/Develop: Difference between revisions

From KitwarePublic
< CMake‎ | Git
Jump to navigationJump to search
No edit summary
(Replaced content with "The instructions previously available on this page have been superseded. See [https://gitlab.kitware.com/cmake/cmake/blob/master/Help/dev/README.rst here].")
 
(5 intermediate revisions by the same user not shown)
Line 1: Line 1:
__NOTOC__
The instructions previously available on this page have been superseded. See [https://gitlab.kitware.com/cmake/cmake/blob/master/Help/dev/README.rst here].
 
This page documents how to develop CMake through [http://git-scm.com Git].
See our [[CMake/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 CMake 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>
 
==Audience==
 
The instructions on this page are meant for those whom have been invited to gain direct push access to our Git repository.
If you do not have access already, '''please see [http://cmake.org/gitweb?p=cmake.git;a=blob_plain;f=CONTRIBUTING.rst;hb=master CONTRIBUTING.rst] at the top of the source tree'''.
We ask that newcomers join the developer mailing list and send patches.
Productive contributors and module maintainer volunteers may be invited to gain direct access.
 
==Setup==
 
Before you begin, perform initial setup:
 
{| style="width: 100%" cellspacing="0" cellpadding="0"
|-
|width=60%|
1.
Register [[CMake/Git/Account#Git|Git push access]] (after having been invited as described [[#Audience|above]]).
|-
|
2.
Follow the [[CMake/Git/Download#Clone|download instructions]] to create a local CMake clone:
|-
|
:<code>$ git clone git://cmake.org/cmake.git</code>
:<code>$ cd cmake</code>
|align="center"|
[[Git/Trouble#Firewall_Blocks_Port_9418|Connection refused]]?
|-
|
3.
Run the developer setup script to prepare your CMake work tree:
|-
|
:<code>$ ./Utilities/SetupForDevelopment.sh</code>
|align="center"|
[http://cmake.org/gitweb?p=cmake.git;a=blob;f=Utilities/SetupForDevelopment.sh;hb=HEAD <code>SetupForDevelopment.sh</code>]
|}
 
==Workflow==
 
CMake development uses a [[Git/Workflow/Topic|branchy workflow]] based on topic branches using the CMake [[Git/Workflow/Stage|Topics Stage]].
 
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 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>
:''(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-checkout.html <code>git help checkout</code>]
<br/>
[http://git-scm.com/book/en/Git-Branching-Rebasing 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]
|-
|
If your change is user-facing please create a <code>Help/release/dev/''my-topic''.rst</code> document with release notes.
(This is not necessary for minor or internal bug fixes.)
 
''(If your change modifies the "<code>Source/kwsys</code>" directory please contribute directly to [[KWSys/Git|KWSys]] instead.)''
|-
|
If you started from <code>origin/release</code> and the topic conflicts with <code>origin/master</code>, finish the topic with a merge from master to resolve them:
|-
|
:<code>$ git fetch origin master:master</code>
:<code>$ git merge master</code>
|}
 
==Share a Topic==
 
When a topic is ready for testing and review by others, share it by pushing it to the "[http://public.kitware.com/Wiki/Git/Workflow/Stage topic stage]".
Be sure you have registered for [[CMake/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 log origin/master..</code>
|align="center"|
[http://schacon.github.com/git/git-log.html <code>git help log</code>]
|-
|
Push commits in your topic branch to the topic stage (be sure to have [[#Setup|set up]] for development):
|-
|
:<code>$ git push stage HEAD</code>
|align="center"|
[http://schacon.github.com/git/git-push.html <code>git help push</code>]
|-
|
The topic is now published on the [http://cmake.org/stage/cmake.git CMake Topic Stage] and may be (optionally) reviewed by others.
If you would like review by others before merging for testing in the next step, please post to the cmake-developers mailing list.
 
''Note: Please do not push a topic to the stage unless you are ready to '''immediately''' send an email to the mailing list to ask for review and/or merge it to '''next''' for testing.''
''If you push a topic and then change your mind, please remove it with''
:<code>$ git push stage :''my-topic''</code>
''We do not want to accumulate partially completed topics that obscure those really ready for review and integration.''
|}
 
==Merge a Topic for Testing==
 
When your topic is ready, merge it to the CMake '''next''' branch for testing.
 
{| style="width: 100%"
|-
|width=60%|
Ask the topic stage to automatically merge the topic to '''next''':
|-
|
:<code>$ ssh git@cmake.org stage cmake merge -b next ''my-topic''</code>
:''(If the merge conflicts follow the printed instructions to resolve them.)''
|align="center"|
[[Git/Workflow/Topic/Conflicts#Topic-to-Topic|Topic-to-Topic Conflict Resolution]]
|-
|
The topic is now integrated into CMake's '''next''' branch and will be tested by dashboard builds.
 
If the topic modifies documentation, check the
[http://open.cdash.org/index.php?project=CMake#Continuous_Help Continuous Help]
section of the dashboard for errors and warnings from sphinx-build.
 
Documentation generated from the '''next''' branch will be published within 10 minutes
[http://www.cmake.org/cmake/help/git-next/ here].
This is intended for reference by developers to see how the documentation renders as changes are made.
Do not publish links pointing anywhere but the top-level page because deeper pages are not stable.
|}
 
==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>
|align="center"|
[http://schacon.github.com/git/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://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]
|-
|
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''' 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.
 
Documentation generated from the '''master''' branch will be published within 10 minutes
[http://www.cmake.org/cmake/help/git-master/ here].
This is intended for reference by developers to see how the documentation renders as changes are made.
Do not publish links pointing anywhere but the top-level page because deeper pages are not stable.
 
==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).
|}

Latest revision as of 15:16, 6 March 2017

The instructions previously available on this page have been superseded. See here.