|
|
| (One intermediate revision 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 https://cmake.org/cmake.git</code>
| |
| :<code>$ cd cmake</code>
| |
| |align="center"|
| |
| |-
| |
| |
| |
| 3.
| |
| Run the developer setup script to prepare your CMake work tree:
| |
| |-
| |
| |
| |
| :<code>$ ./Utilities/SetupForDevelopment.sh</code>
| |
| |align="center"|
| |
| [https://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 [https://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.
| |
| | |
| After merging, please check the [http://open.cdash.org/index.php?project=CMake#Continuous Continuous]
| |
| section of the dashboard for the rest of the day and diligently follow up on any problems introduced.
| |
| 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.
| |
| | |
| On the day after merging, check the [http://open.cdash.org/index.php?project=CMake Entire Dashboard]
| |
| and follow up with fixes as described in the [[#Extend_a_Topic|next step]].
| |
| | |
| 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).
| |
| |}
| |
