Merge pull request #108 from jim-parry/guidelines

Update the contributing guide & process to explain signed commits.

Author: lonnieezell

system/Debug/CustomExceptions.php

@@ -1,4 +1,6 @@
-<?php namespace CodeIgniter;
+<?php
+
+namespace CodeIgniter;
 
 /**
  * CodeIgniter
@@ -35,48 +37,57 @@
  * @since	Version 3.0.0
  * @filesource
  */
-
 /**
  * Custom Exceptions
  *
- * These exceptions are provided for you use, and work to provide a consistent
+ * These exceptions are provided for your use, and work to provide a consistent
  * experience across the application. The default error codes are already set,
  * and will be used to provide both HTTP status codes and CLI exit codes.
  *
+ * The Error Exceptions below are primarily to provide a way to have 
+ * information logged automatically by the application's log system.
+ * 
  * @package CodeIgniter
  */
 
-
-/*
-	The Error Exceptions below are primarily to provide a way to have information logged
-	automatically by the application's log system.
-*/
-
 /**
- * Exception for automatic logging.
+ * Error: system is unusable
  */
-class EmergencyError extends \Error {};  // system is unusable
+class EmergencyError extends \Error
+{
+	
+}
 
 /**
- * Exception for automatic logging.
+ * Error: Action must be taken immediately (system/db down, etc)
  */
-class AlertError     extends \Error {};  // Action must be taken immediately (system/db down, etc)
+class AlertError extends \Error
+{
+	
+}
 
 /**
- * Exception for automatic logging.
+ * Error: Critical conditions, like component unavailble, etc.
  */
-class CriticalError  extends \Error {};  // Critical conditions, like component unavailble, etc.
+class CriticalError extends \Error
+{
+	
+}
 
 /**
- * Exception for automatic logging.
+ * Error: Runtime errors that do not require immediate action
  */
-class Error          extends \Error {};  // Runtime errors that do not require immediate action
+class Error extends \Error
+{
+	
+}
 
 /**
  * Exception for automatic logging.
  */
 class PageNotFoundException extends \OutOfBoundsException
 {
+
 	/**
 	 * Error code
 	 * @var int 
@@ -85,13 +96,12 @@ class PageNotFoundException extends \OutOfBoundsException
 
 }
 
-;
-
 /**
  * Exception for automatic logging.
  */
 class ConfigException extends CriticalError
 {
+
 	/**
 	 * Error code
 	 * @var int 
@@ -100,13 +110,12 @@ class ConfigException extends CriticalError
 
 }
 
-;
-
 /**
  * Exception for automatic logging.
  */
 class UnknownFileException extends CriticalError
 {
+
 	/**
 	 * Error code
 	 * @var int 
@@ -115,13 +124,12 @@ class UnknownFileException extends CriticalError
 
 }
 
-;
-
 /**
  * Exception for automatic logging.
  */
 class UnknownClassException extends CriticalError
 {
+
 	/**
 	 * Error code
 	 * @var int 
@@ -130,13 +138,12 @@ class UnknownClassException extends CriticalError
 
 }
 
-;
-
 /**
  * Exception for automatic logging.
  */
 class UnknownMethodException extends CriticalError
 {
+
 	/**
 	 * Error code
 	 * @var int 
@@ -145,13 +152,12 @@ class UnknownMethodException extends CriticalError
 
 }
 
-;
-
 /**
  * Exception for automatic logging.
  */
 class UserInputException extends \OutOfBoundsException
 {
+
 	/**
 	 * Error code
 	 * @var int 
@@ -160,19 +166,16 @@ class UserInputException extends \OutOfBoundsException
 
 }
 
-;
-
 /**
  * Exception for automatic logging.
  */
 class DatabaseException extends Error
 {
+
 	/**
 	 * Error code
 	 * @var int 
 	 */
 	protected $code = 8;
 
 }
-
-;

user_guide_src/source/contributing/guidelines.rst

@@ -67,6 +67,8 @@ Change Log
 ==========
 
 The change-log, in the user guide root, needs to be kept up-to-date.
+Not all changes will need an entry in it, but new classes, major or BC changes
+to existing classes, and bug fixes should.
 
 See the `CodeIgniter 3 change log 
 <https://github.com/bcit-ci/CodeIgniter/blob/develop/user_guide_src/source/changelog.rst>`_ 

user_guide_src/source/contributing/process.rst

@@ -23,11 +23,21 @@ at the same time, we might really want X but disagree with Y, meaning we
 cannot merge the request. Using the Git-Flow branching model you can create
 new branches for both of these features and send two requests.
 
-Signing
-=======
+Basic Signing
+=============
 You must sign your work, certifying that you either wrote the work or
-otherwise have the right to pass it on to an open source project. git makes
-this easy as you merely have to use `--signoff` on your commits to your
+otherwise have the right to pass it on to an open source project. 
+
+Setup your commit message user name and email address. See 
+`Setting your email in Git <https://help.github.com/articles/setting-your-email-in-git/>`_
+to set these up globally or for a single repository.
+
+.. code-block:: bash
+
+	git config --global user.email "john.public@example.com"
+	git config --global user.name "John Q Public"
+ 
+Once in place, you merely have to use `--signoff` on your commits to your
 CodeIgniter fork.
 
 .. code-block:: bash
@@ -52,3 +62,25 @@ it.
 By signing your work in this manner, you certify to a "Developer's Certificate
 of Origin". The current version of this certificate is in the :doc:`/DCO` file
 in the root of this documentation.
+
+Secure Signing
+==============
+
+The "basic signing" described above cannot be verified, though it is a great start.
+To verify your commits, you will need to 
+setup a GPG key, and attach it to your github account.
+
+See the `git tools <https://git-scm.com/book/en/v2/Git-Tools-Signing-Your-Work>`_
+page for directions on doing this. The complete story is part of
+`Github help <https://help.github.com/categories/gpg/>`_.
+
+The basic steps are
+
+-  `generate your GPG key <https://help.github.com/articles/generating-a-new-gpg-key/>`_, and copy the ASCII representation of it.
+-  `Add your GPG key to your Github account <https://help.github.com/articles/adding-a-new-gpg-key-to-your-github-account/>`_. 
+-   `Tell Git <https://help.github.com/articles/telling-git-about-your-gpg-key/>`_ about your GPG key.
+-   `Set default signing <https://help.github.com/articles/signing-commits-using-gpg/>`_ to have all of your commits securely signed automatically.
+-   Provide your GPG key passphrase, as prompted, when you do a commit.
+
+Depending on your IDE, you may have to do your Git commits from your Git bash shell 
+to use the **-S** option to force the secure signing.

user_guide_src/source/contributing/styleguide.rst

@@ -47,6 +47,20 @@ Structure
 =========
 
 - A single file SHOULD NOT declare more than one class.
+  Examples where we feel that more than one class in a source file
+  is appropriate:
+
+    -   `system/Debug/CustomExceptions` contains a number of CodeIgniter
+        exceptions and errors, that we want to use for a consistent
+        experience across applications. 
+        If we stick with the purist route, then each of the 13+/- custom 
+        exceptions would require an additional file, which would have a 
+        performance impact at times. 
+    -   `system/HTTP/Response` provides a RedirectException, used with the
+        Response class.
+    -   `system/Router/Router` similarly provides a RedirectException, used with 
+        the Router class.
+
 - Files SHOULD either declare symbols (i.e. classes, functions, constants)
   or execute non-declarative logic, but SHOULD NOT do both.
 
@@ -185,6 +199,25 @@ Operators
 - An operator MUST NOT be the last set of printable characters on a line.
 - An operator MAY be the first set of printable characters on a line.
 
+Logical Operators
+=================
+
+-   Use the symbol versions (**||** and **&&**) of the logical operators
+    instead of the word versions (**OR** and **AND**).
+
+        -   This is consistent with other programming languages
+        -   It avoids the problem of the assignment operator (**=**) having
+            higher precedence::
+
+                $result = true && false; // $result is false, expected
+                $result = true OR false; // $result is true, evaluated as "($result = true) OR false"
+                $result = (true OR false); // $result is false
+
+-   The logical negation operator MUST be separated from its argument by a
+    single space, as in **! $result** instead of **!$result**
+-   If there is potential confusion with a logical expression, then use
+    parentheses for clarity, as shown above.
+
 Other
 =====