contribution: rewrite guidelines and add commit examples

- use 80 characters line break
- rewrite GitHub guide
- Updated commit message guide
- explain workflows a bit better

1 files changed, 116 insertions, 140 deletions

diff --git a/docs/contributing/development.rst b/docs/contributing/development.rst
index 9e99ece8..3ac9cf6f 100644
--- a/docs/contributing/development.rst
+++ b/docs/contributing/development.rst
@@ -3,199 +3,175 @@
 Development
 ===========
 
-The source code is hosted on GitHub under VyOS organization `github.com/vyos`_
+All VyOS source code is hosted on GitHub under the VyOS organization which can
+be found here: https://github.com/vyos
 
-The code is split into modules. VyOS is composed of multiple individual packages,
-some of them are periodically synced with upstream, so keeping the whole source
-under a single repository would be very inconvenient and slow. There is now an
-ongoing effort to consolidate all VyOS-specific framework/config packages into vyos-1x package,
-but the basic structure is going to stay the same, just with fewer packages.
+Our code is split into several modules. VyOS is composed of multiple individual
+packages, some of them are forks of upstream packages and are periodically
+synced with upstream, so keeping the whole source under a single repository
+would be very inconvenient and slow. There is now an ongoing effort to
+consolidate all VyOS-specific framework/config packages into vyos-1x package,
+but the basic structure is going to stay the same, just with fewer and fewer
+packages while the base code is rewritten from Perl/BASH into Python using and
+XML based interface definition for the CLI.
 
-The repository that contains the ISO build script is `vyos-build`_. The README will
-guide you to use the this top level repository.
+The repository that contains all the ISO build scripts is:
+https://github.com/vyos/vyos-build
+
+The README.md file will guide you to use the this top level repository.
 
-.. _github.com/vyos: https://github.com/vyos
-.. _vyos-build: https://github.com/vyos/vyos-build
 
 Submit a patch
 --------------
 
-Patches are always welcome.
-You should follow some procedures and guidelines though.
-
-Before you make a patch
-^^^^^^^^^^^^^^^^^^^^^^^
-In a big system, such as VyOS, that is comprised of multiple components, it's impossible to keep track of all the changes and bugs/feature requests in one's head. We use a `bugtracker`_ for it ("issue tracker" would be a better term, but this one stuck).
-
-This information is used in two ways:
-  * Keep track of the progress (what we've already done in this branch and what we still need to do).
-  * Prepare release notes.
-
-To make this approach work, every change must be associated with a bug number and component.
-If there is no bug/enhancement request for the changes you are going to make, you must create a `bugtracker`_ entry first.
-Once there is a `bugtracker`_ entry about it, you should reference in your commit message, as in:
-
-.. code-block:: sh
-
-  [vyos build] T1327: add serial console (115200,8n1) to ISO kernel command-line
-  [vyos config] T1397: Rewrite the config merge script
-
-If there is no reference to an item in our `bugtracker`_ the pull request will be rejected.
-
-Patch limits:
-  * If there is a bug that has multiple tasks than it is ok to reference multiple items in a commit and pull request.
-  * Multiple bugs can not be fixed in one patch if they have no reference to each other.
-  * We only accept bugfixes in packages other than vyos-1x.
-  * No new functionality should use old style templates and perl/shell code, use python.
-
-.. _bugtracker: https://phabricator.vyos.net
-
-How to make a patch
-^^^^^^^^^^^^^^^^^^^
-We only accept patches in git format, because traditional UNIX patch is only good if the code it's going to be applied to doesn't change. If the code changes, merge will fail and the patch will need manual editing, even if there are no real conflicting changes.
-
-Git keeps more information and uses more sophisticated merge algorithms, which makes a fake conflict a rare occurrence. For the same reason you should always make a patch against the latest current branch.
-
-You can make a pull request on `github.com/vyos`_. 
-
-.. _github.com/vyos: https://github.com/vyos
-
-Find the package
-^^^^^^^^^^^^^^^^
-Suppose you want to make a change in the webproxy script.
-
-You can find its package with "dpkg -S":
-
-.. code-block:: sh
-
-  # dpkg -S /opt/vyatta/sbin/vyatta-update-webproxy.pl 
-  vyatta-webproxy: /opt/vyatta/sbin/vyatta-update-webproxy.pl
-
-This means it's in `vyatta-webproxy`_ package.
+Patches are always more then welcome. To have a clean and easy to maintain
+repository we have some guidelines when working with Git. A clean repository
+eases the automatic generation of a changelog file.
 
-.. _vyatta-webproxy: https://github.com/vyos/vyatta-webproxy
+A good approach for writing commit messages is actually to have a look at the
+file(s) history by invoking ``git log path/to/file.txt``.
 
-Make a patch using a fork
-^^^^^^^^^^^^^^^^^^^^^^^^^
-Fork the repository in github and make a clone.
 
-.. code-block:: sh
+Preparding patch/commit
+^^^^^^^^^^^^^^^^^^^^^^^
 
-  git clone https://github.com/<user>/vyatta-webproxy.git
+In a big system, such as VyOS, that is comprised of multiple components, it's
+impossible to keep track of all the changes and bugs/feature requests in one's
+head. We use a bugtracker known as Phabricator_ for it ("issue tracker" would
+be a better term, but this one stuck).
 
-Set your name and email in the git config:
+The information is used in two ways:
 
-.. code-block:: sh
+* Keep track of the progress (what we've already done in this branch and what
+  we still need to do).
 
-  git config user.name "J. Random Hacker"
-  git config user.email "jrhacker@example.net"
+* Prepare release notes for upcoming releases
 
-Make your changes and save them. Then do the following for all changes files:
+To make this approach work, every change must be associated with a bug number
+(prefixed with **T**) and a component. If there is no bug report/feature request
+for the changes you are going to make, you have to create a Phabricator_ task
+first. Once there is an entry in Phabricator_, you should reference its id in
+your commit message, as shown below:
 
-.. code-block:: sh
+* ``ddclient: T1030: auto create runtime directories``
+* ``Jenkins: add current Git commit ID to build description``
 
-  git add myfile
+If there is no Phabricator_ reference in the commits of your pull request, we
+have to ask you to ammend the commit message. Otherwise we will have to reject
+it.
 
-  # Or, for a whole dir:
-  git add somedir/*
+In general, use an editor to create your commit messages rather than passing
+them on the command line. The format should be and is inspired by this blog
+post: http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html
 
-Commit the changes:
+* A single, short, summary of the commit (recommended 70 characters or less,
+  but not exceeding 80 characters)
 
-.. code-block:: sh
+  * Add a prefix of the changed component to your commit headline, e.g. ``snmp:
+    T1111:`` or ``ethernet: T2222:``. If multiple components are touched by this
+    commit, you can use multiple prefixes, e.g.: ``snmp: ethernet:``
 
-  git commit
+* Followed by a blank line (this is mandatory - else Git will treat the whole
+  commit message as the headline only)
 
-Please use meaningful commit descriptions and don't forget to reference the bug number there!
-Now submit the patch, push and make a pull request.
+* Followed by a message which describes all the details like:
 
-Make a patch to mail or attach to an item
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-clone the repository.
+  * What/why/how something has been changed, makes everyones life easier when
+    working with `git bisect`
 
-.. code-block:: sh
+  * All text of the commit message should be wrapped at 72 characters if
+    possible which makes reading commit logs easier with ``git log`` on a
+	standard terminal (which happens to be 80x25)
 
-  git clone https://github.com/vyos/vyatta-webproxy.git
+  * If applicable a reference to a previous commit should be made linking
+    those commits nicely when browsing the history: ``After commit abcd12ef
+	("snmp: this is a headline") a Python import statement is missing,
+	throwing the follwoing exception: ABCDEF``
 
-Set your name and email in the git config:
+* Always use the ``-x`` option to the ``git cherry-pick`` command when back or
+  forward porting an individual commit. This automatically appends the line:
+  ``(cherry picked from commit <ID>)`` to the original authors commit message
+  making it easier when bisecting problems.
 
-.. code-block:: sh
+* Every change set must be consistent (self containing)! Do not fix multiple
+  bugs in a single commit. If you already worked on multiple fixes in the same
+  file use `git add --patch` to only add the parts related to the one issue
+  into your upcoming commit.
 
-  git config user.name "J. Random Hacker"
-  git config user.email "jrhacker@example.net"
+Limits:
 
-Make your changes and save them. Then do the following for all changes files:
+* We only accept bugfixes in packages other than https://github.com/vyos/vyos-1x
+  as no new functionality should use the old style templates (``node.def`` and
+  Perl/BASH code. Use the new stlye XML/Python interface instead.
 
-.. code-block:: sh
+Please submit your patches using the well-known GitHub pull-request against our
+repositories found in the VyOS GitHub organisation at https://github.com/vyos
 
-  git add myfile
 
-  # Or, for a whole dir:
-  git add somedir/*
+Determining package for a fix
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-Commit the changes:
+Suppose you want to make a change in the webproxy script but yet you do not know
+which of the many VyOS packages ship this file. You can determine the VyOS
+package name in question by using Debians ``dpkg -S`` command of your running
+VyOS installation.
 
 .. code-block:: sh
 
-  git commit
-
-Please use meaningful commit descriptions and don't forget to reference the bug number there!
-Export the patch and send it to maintainers@vyos.net or attach to the bug. 
-
-.. code-block:: sh
-
-  git format-patch
-
-  # Or, for multiple commits, suppose you made two:
-  git format-patch -2
-
-Make a patch using a feature branch (maintainers only)
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-checkout the current branch and make sure it is up to date.
-
-.. code-block:: sh
+  vyos@vyos:~ dpkg -S /opt/vyatta/sbin/vyatta-update-webproxy.pl
+  vyatta-webproxy: /opt/vyatta/sbin/vyatta-update-webproxy.pl
 
-  git clone https://github.com/vyos/vyatta-webproxy.git
-  git checkout current
-  git pull origin current
+This means the file in question (``/opt/vyatta/sbin/vyatta-update-webproxy.pl``)
+is located in the ``vyatta-webproxy`` package which can be found here:
+https://github.com/vyos/vyatta-webproxy
 
-Set your name and email in the git config:
 
-.. code-block:: sh
+Fork repository to submit a Patch
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-  git config user.name "J. Random Hacker"
-  git config user.email "jrhacker@example.net"
+Forking the repository and submitting a GitHub pull-request is the preferred
+way of submitting your changes to VyOS. You can fork any VyOS repository to your
+very own GitHub account by just appending ``/fork`` to any repositories URL on
+GitHub. To e.g. fork the ``vyos-1x`` repository, open the following URL in your
+favourite browser: https://github.com/vyos/vyos-1x/fork
 
-Create the feature branch:
+You then can proceed with cloning your fork or add a new remote to your local
+repository:
 
-.. code-block:: sh
+* Clone: ``git clone https://github.com/<user>/vyos-1x.git``
 
-  git checkout -b <feature branch name>
+* Fork: ``git remote add myfork https://github.com/<user>/vyos-1x.git``
 
-Make your changes and save them. Then do the following for all changes files:
+In order to record you as the author of the fix please indentify yourself to Git
+by setting up your name and email. This can be done local for this one and only
+repository ``git config`` or globally using ``git config --global``.
 
 .. code-block:: sh
 
-  git add myfile
+  git config --global user.name "J. Random Hacker"
+  git config --global user.email "jrhacker@example.net"
 
-  # Or, for a whole dir:
-  git add somedir/*
+Make your changes and save them. Do the following for all changes files to
+record them in your created Git commit:
 
-Commit the changes:
+* Add file to Git index using ``git add myfile``, or for a whole directory:
+  ``git add somedir/*``
 
-.. code-block:: sh
+* Commit the changes by calling ``git commit``. Please use a meaningful commit
+  headline (read above) and don't forget to reference the Phabricator_ ID.
 
-  git commit
+* Submit the patch ``git push`` and create the GitHub pull-request.
 
-Please use meaningful commit descriptions and don't forget to reference the bug number there!
 
-Rebase on the current repo if needed and push your branch
+Attach patch to Phabricator task
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-.. code-block:: sh
+Follow the above steps on how to "Fork repository to submit a Patch". Instead
+of uploading "pushing" your changes to GitHub you can export the patches/
+commits and send it to maintainers@vyos.net or attach it directly to the bug
+(preferred over email)
 
-  git checkout current
-  git pull origin current
-  git checkout <feature branch name>
-  git rebase current
-  git push -u origin <feature branch name>
+* Export last commit to patch file: ``git format-patch`` or export the last two
+  commits into its appropriate patch files: ``git format-patch -2``
 
-Now you create a pull request.
+.. _Phabricator: https://phabricator.vyos.net
\ No newline at end of file