Updated coding guide to include some info on pull requests

timlinux · timlinux · commit 6c2e385a986c · 2014-01-03T17:21:59.000+02:00
diff --git 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 and pull
+requests into QGIS easily, and help us deal with the patches that are sent to
+use easily. 
+
+
+    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):
 
-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.
+* 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.1. Patch file naming
+    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
@@ -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 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):
 
-== Submitting Patches ==
+* 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 ===
 
