From 6c2e385a986c066106e801ab6b45d1cfa198a6a6 Mon Sep 17 00:00:00 2001 From: Tim Sutton Date: Fri, 3 Jan 2014 17:21:40 +0200 Subject: [PATCH] Updated coding guide to include some info on pull requests --- CODING | 74 ++++++++++++++++++++++++++++++++++++-------------- doc/CODING.t2t | 54 ++++++++++++++++++++++++++++-------- 2 files changed, 96 insertions(+), 32 deletions(-) diff --git a/CODING b/CODING index d393f9e11de..1b99c211d5f 100644 --- a/CODING +++ b/CODING @@ -45,11 +45,12 @@ Developers guide for QGIS 2.6. Development in branches 2.6.1. Purpose 2.6.2. Procedure - 2.7. Submitting Patches - 2.7.1. Patch file naming - 2.7.2. Create your patch in the top level QGIS source dir - 2.7.3. Getting your patch noticed - 2.7.4. Due Diligence + 2.7. Submitting Patches and Pull Requests + 2.7.1. Pull Requests + 2.7.2. Patch file naming + 2.7.3. Create your patch in the top level QGIS source dir + 2.7.4. Getting your patch noticed + 2.7.5. Due Diligence 2.8. Obtaining GIT Write Access 3. Unit Testing 3.1. The QGIS testing framework - an overview @@ -509,11 +510,9 @@ development versions. If you're interested in checking out QGIS documentation sources: - svn co https://svn.osgeo.org/qgis/docs/trunk qgis_docs + git clone git@github.com:qgis/QGIS-Documentation.git -/!\ Note: This url will change to a git URL in the near future. - -You can also take a look at DocumentationWritersCorner for more information. +You can also take a look at the readme included with the documentation repo for more information. 2.5. GIT Documentation @@ -584,20 +583,53 @@ of the work on a wiki page. Testing before merging back to master: When you are finished with the new feature and happy with the stability, make an announcement on the developer list. Before merging back, the changes will -be tested by developers and users. Binary packages (especially for OsX and -Windows) will be generated to also involve non-developers. In trac, a new -Component will be opened to file tickets against. Once there are no remaining -issues left, the technical advisor of the PSC merges the changes into master. +be tested by developers and users. - 2.7. Submitting Patches - ======================= + 2.7. Submitting Patches and Pull Requests + ========================================= -There are a few guidelines that will help you to get your patches into QGIS -easily, and help us deal with the patches that are sent to use easily. +There are a few guidelines that will help you to get your patches and pull +requests into QGIS easily, and help us deal with the patches that are sent to +use easily. - 2.7.1. Patch file naming + 2.7.1. Pull Requests + ==================== + +In general it is easier for developers if you submit GitHub pull +requests. We do not describe Pull Requests here, but rather refer you to the +GitHub pull request documentation here: + +https://help.github.com/articles/using-pull-requests + +If you make a pull request we ask that you please merge master to your PR +branch regularly so that your PR is always mergable to the upstream master +branch. + +If you are a developer and wish to evaluate the pull request queue, there is a +very nice tool that lets you do this from the command line described here: + +http://thechangelog.com/git-pulls-command-line-tool-for-github-pull-requests/ + +Please see the section below on 'getting your patch noticed'. In general when +you submit a PR you should take the responsibility to follow it through to +completion - respond to queries posted by other developers, seek out a +'champion' for your feature and give them a gentle reminder occasionally if you +see that your PR is not being acted on. Please bear in mind that the QGIS +project is driven by volunteer effort and people may not be able to attend to +your PR instantaneously. If you feel the PR is not receiving the attention it +deserves your options to accelerate it should be (in order of priority): + +* Send a message to the mailing list 'marketing' your PR and how wonderful it + will be to have it included in the code base. +* Send a message to the person your PR has been assigned to in the PR queue. +* Send a message to Marco Hugentobler (who manages the PR queue). +* Send a message to the project steering committee asking them to help see your + PR incorporated into the code base. + + + 2.7.2. Patch file naming ======================== If the patch is a fix for a specific bug, please name the file with the bug @@ -608,7 +640,7 @@ If the bug is an enhancement or new feature, its usually a good idea to create a ticket in trac (http://hub.qgis.org/projects/quantum-gis) first and then attach you - 2.7.2. Create your patch in the top level QGIS source dir + 2.7.3. Create your patch in the top level QGIS source dir ========================================================= This makes it easier for us to apply the patches since we don't need to @@ -629,7 +661,7 @@ and then generate a patch which contains the delta between your feature branch and what is in the master branch. - 2.7.3. Getting your patch noticed + 2.7.4. Getting your patch noticed ================================= QGIS developers are busy folk. We do scan the incoming patches on bug reports @@ -640,7 +672,7 @@ can escalate your query to one of the Project Steering Committee members (contact details also available on the Project Organigram). - 2.7.4. Due Diligence + 2.7.5. Due Diligence ==================== QGIS is licensed under the GPL. You should make every effort to ensure you only diff --git a/doc/CODING.t2t b/doc/CODING.t2t index 58e75953efd..d260095a72e 100644 --- a/doc/CODING.t2t +++ b/doc/CODING.t2t @@ -489,12 +489,10 @@ development versions. If you're interested in checking out QGIS documentation sources: ``` - svn co https://svn.osgeo.org/qgis/docs/trunk qgis_docs + git clone git@github.com:qgis/QGIS-Documentation.git ``` -/!\ **Note:** This url will change to a git URL in the near future. - -You can also take a look at DocumentationWritersCorner for more information. +You can also take a look at the readme included with the documentation repo for more information. == GIT Documentation == @@ -507,6 +505,7 @@ http://gitready.com == Development in branches == === Purpose === + The complexity of the QGIS source code has increased considerably during the last years. Therefore it is hard to anticipate the side effects that the addition of a feature will have. In the past, the QGIS project had very long @@ -560,16 +559,49 @@ of the work on a wiki page. **Testing before merging back to master:** When you are finished with the new feature and happy with the stability, make an announcement on the developer list. Before merging back, the changes will -be tested by developers and users. Binary packages (especially for OsX and -Windows) will be generated to also involve non-developers. In trac, a new -Component will be opened to file tickets against. Once there are no remaining -issues left, the technical advisor of the PSC merges the changes into master. +be tested by developers and users. -== Submitting Patches == +== Submitting Patches and Pull Requests == + +There are a few guidelines that will help you to get your patches and pull +requests into QGIS easily, and help us deal with the patches that are sent to +use easily. + + +=== Pull Requests === + +In general it is easier for developers if you submit GitHub pull +requests. We do not describe Pull Requests here, but rather refer you to the +GitHub pull request documentation here: + +https://help.github.com/articles/using-pull-requests + +If you make a pull request we ask that you please merge master to your PR +branch regularly so that your PR is always mergable to the upstream master +branch. + +If you are a developer and wish to evaluate the pull request queue, there is a +very nice tool that lets you do this from the command line described here: + +http://thechangelog.com/git-pulls-command-line-tool-for-github-pull-requests/ + +Please see the section below on 'getting your patch noticed'. In general when +you submit a PR you should take the responsibility to follow it through to +completion - respond to queries posted by other developers, seek out a +'champion' for your feature and give them a gentle reminder occasionally if you +see that your PR is not being acted on. Please bear in mind that the QGIS +project is driven by volunteer effort and people may not be able to attend to +your PR instantaneously. If you feel the PR is not receiving the attention it +deserves your options to accelerate it should be (in order of priority): + +* Send a message to the mailing list 'marketing' your PR and how wonderful it + will be to have it included in the code base. +* Send a message to the person your PR has been assigned to in the PR queue. +* Send a message to Marco Hugentobler (who manages the PR queue). +* Send a message to the project steering committee asking them to help see your + PR incorporated into the code base. -There are a few guidelines that will help you to get your patches into QGIS -easily, and help us deal with the patches that are sent to use easily. === Patch file naming ===