Merge lp:~linuxjedi/drizzle/trunk-bug-724176 into lp:drizzle/7.0

[Andrew Hutchings]

Add basic contributing section to docs

=== modified file 'docs/clients/drizzledump.rst'
--- docs/clients/drizzledump.rst	2011-02-23 17:07:17 +0000
+++ docs/clients/drizzledump.rst	2011-02-24 15:02:57 +0000
@@ -6,9 +6,9 @@
 
 :program:`drizzledump` [:ref:`OPTIONS <drizzledump-options-label>`] *database* [*tables*]
 
-:program:`drizzledump` [:ref:`OPTIONS <drizzledump-options-label>`] :option:`--databases` *DB1* [*DB2* *DB3*...]
+:program:`drizzledump` [:ref:`OPTIONS <drizzledump-options-label>`] :option:`--databases <drizzledump --databases>` *DB1* [*DB2* *DB3*...]
 
-:program:`drizzledump` [:ref:`OPTIONS <drizzledump-options-label>`] :option:`--all-databases`
+:program:`drizzledump` [:ref:`OPTIONS <drizzledump-options-label>`] :option:`--all-databases <drizzledump --all-databases>`
 
 Description
 -----------

=== added directory 'docs/contributing'
=== added file 'docs/contributing/code.rst'
--- docs/contributing/code.rst	1970-01-01 00:00:00 +0000
+++ docs/contributing/code.rst	2011-02-24 15:02:57 +0000
@@ -0,0 +1,103 @@
+.. _code-label:
+
+Contributing Code
+=================
+
+SSH Keys
+--------
+
+You will need to add a public SSH key to Launchpad to be able to push branches
+up for merging.  To do this:
+
+ #. Generate an SSH key (information on how to do this is in `Launchpad's help pages <https://help.launchpad.net/YourAccount/CreatingAnSSHKeyPair>`_)
+ #. Go to `your SSH keys page <https://launchpad.net/people/+me/+editsshkeys>`_
+ #. Paste your public key into the text box and click the *Import public key*
+    button
+
+Getting the Code
+----------------
+
+You will need to prepare a directory for working with Drizzle, the following
+example will assume you want to do this in ~/repos/drizzle:
+
+.. code-block:: bash
+
+   mkdir ~/repos
+   cd ~/repos
+   bzr init-repo drizzle
+
+At this stage you now have an initialized a directory for bzr to use.  Revision
+data will be stored here to save it having to be downloaded/stored for every
+branch.
+
+.. code-block:: bash
+
+   cd drizzle
+   bzr branch lp:drizzle trunk
+
+This will take a little while, it is getting all the revisions since the
+beginning of the repository.  This should only ever need to be done once though.
+
+.. code-block:: bash
+
+   bzr branch trunk drizzle-bug-NNNNNN
+   cd drizzle-bug-NNNNNN
+
+This creates a branch from trunk for you to work on.
+
+Committing Work
+---------------
+
+All commits need to have a proper description of the changes made.  This is so
+that future developers can dig through the bzr log to find out why a certain
+change happened.
+
+When committing a bug fix please use:
+
+.. code-block:: bash
+
+   bzr commit --fixes lp:NNNNNN
+
+This will automatically attach the branch to the bug report when the branch is
+pushed up.
+
+Coding Standards
+----------------
+
+Our coding standards can be found inside the
+`Drizzle wiki <http://wiki.drizzle.org/Coding_Standards>`_.
+
+Test Cases
+----------
+
+Where possible SQL test cases should be created for your code.  Our test cases
+for bug fixes should be in the ``tests/suite/regression`` directory.  For more
+information about creating test cases please see the :ref:`test run <test-run-label>`
+section of our documentation.
+
+Pushing Work
+------------
+
+When you want to push your branch to Launchpad for others to see or for merging
+you can use:
+
+.. code-block:: bash
+
+   bzr push lp:~username/drizzle/trunk-bug-NNNNNN
+
+This will create the branch on Launchpad which you will be able to see on the
+`code page <https://code.launchpad.net/drizzle>`_.  If you make some more commits you simply need to do just ``bzr push`` to get those revisions on Launchpad
+too.
+
+Merge Proposals
+---------------
+
+Once your work is done and ready for review you can go to the
+`code page <https://code.launchpad.net/drizzle>`_, click on your branch and you
+will see a link saying *Propose for merging*.
+
+In this screen simply fill in what this branch does and click the
+*Propose Merge* button.  Someone will review the branch, usually within a day or
+two and if approved it will go though our rigourous testing process which can
+take several hours.  If it needs more work feedback will always be given to
+explain why.

=== added file 'docs/contributing/documentation.rst'
--- docs/contributing/documentation.rst	1970-01-01 00:00:00 +0000
+++ docs/contributing/documentation.rst	2011-02-24 15:02:57 +0000
@@ -0,0 +1,242 @@
+.. _documentation-label:
+
+Contributing Documentation
+==========================
+
+Our documentation is written using `Sphinx Documentation Generator <http://sphinx.pocoo.org/>`_ which uses the `reStructuredText <http://docutils.sf.net/rst.html>`_ format.
+
+All our documentation is stored in the main source reporistory in the docs/
+directory, and every merge into trunk triggers a rebuild of our `documentation site <http://docs.drizzle.org/>`_.
+
+Requirements
+------------
+
+We require a minimum of python-sphinx 0.6 to compile the documentation but not
+all of it will build correctly in that version.  For correct documentation
+version 1.0 is required.
+
+When building the documentation warnings become errors, so the documentation
+needs to be warning free in 1.0.
+
+Documentation Files
+-------------------
+
+The documentation files have the .rst extension and are stored in the ``docs/``
+directory.
+
+Contents
+^^^^^^^^
+
+To add a new document to the contents you will need to add it to a relevent
+section in the ``docs/index.rst`` file.
+
+Plugins
+^^^^^^^
+
+To document plugins you need to create a ``docs/`` subdirectory in your plugin
+directory containing an index.rst file.  This will be automatically added during
+the ``config/autorun.sh`` phase.
+
+Documentation Format
+--------------------
+
+The documentation is in the reStructured text format which is a wiki-like markup
+laungauge ideal for documentation.
+
+Headings
+^^^^^^^^
+
+Headings take the form of just the text with a diffent style of underline to
+signify the level, for example:
+
+.. code-block:: rest
+   
+   Heading Level 1
+   ===============
+
+   Heading Level 2
+   ---------------
+
+   Heading Level 3
+   ^^^^^^^^^^^^^^^
+
+Tables
+^^^^^^
+
+There are two ways of generating a table, the first is basically drawing the
+entire table in ascii art as follows:
+
+.. code-block:: rest
+
+   +----+--------+-----+
+   | ID | name   | age |
+   +====+========+=====+
+   | 1  | Fred   | 23  |
+   +----+--------+-----+
+   | 2  | Joe    | 48  |
+   +----+--------+-----+
+   | 3  | Sophie | 32  |
+   +----+--------+-----+
+
+Which generates:
+
++----+--------+-----+
+| ID | name   | age |
++====+========+=====+
+| 1  | Fred   | 23  |
++----+--------+-----+
+| 2  | Joe    | 48  |
++----+--------+-----+
+| 3  | Sophie | 32  |
++----+--------+-----+
+
+As an alternative there is a simplified form as follows:
+
+.. code-block:: rest
+
+   ----- ----- ------
+     A     B   Result
+   ===== ===== ======
+   False False False
+   False True  True
+   True  False True
+   True  True  False
+   ===== ===== =====
+
+Gives this table:
+
+===== ===== ======
+  A     B   Result
+===== ===== ======
+False False False
+False True  True
+True  False True
+True  True  False
+===== ===== ======
+
+In this form there must be more than one row to the table and the first column
+can only have a single line.
+
+Syntax Highlighting
+^^^^^^^^^^^^^^^^^^^
+
+Sphinx supports syntax highlighting using the `Pygments <http://pygments.org/>`_
+engine.  For example, with the *mysql* syntax highlighter you can do the
+following:
+
+.. code-block:: rest
+
+   .. code-block:: mysql
+
+      SELECT * FROM t1 WHERE a=1;
+
+Which will generate:
+
+.. code-block:: mysql
+
+   SELECT * FROM t1 WHERE a=1;
+
+You can also add line numbers as follows:
+
+.. code-block:: rest
+
+   .. code-block:: c
+      :linenos:
+
+      #include <stdio.h>
+
+      main()
+      {
+        printf("hello world");
+      }
+
+Which will generate:
+
+.. code-block:: c
+   :linenos:
+
+   #include <stdio.h>
+
+   main()
+   {
+     printf("hello world");
+   }
+
+.. seealso::
+
+   `Pygments Demo <http://pygments.org/demo/>`_ - A demo of the available syntax
+   highlighting types.
+
+Footnotes
+^^^^^^^^^
+
+Footnotes in their most simple form can be generated using ``[1]_`` in the text
+and then a section of the bottom of the page as follows [1]_:
+
+.. code-block:: rest
+
+   .. rubric:: Footnotes
+
+   .. [1] Like this
+
+Which generates:
+
+.. rubric:: Footnotes
+
+.. [1] Like this
+
+Notes, Warnings, Todo and See Also
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Notes, warnings and todos all take similar forms:
+
+.. code-block:: rest
+
+   .. note::
+      This is a note
+
+   .. warning::
+      This is a warning
+
+   .. todo::
+      This is a todo
+
+   .. seealso::
+      This is a See Also
+
+Which generates:
+
+.. note::
+   This is a note
+
+.. warning::
+   This is a warning
+
+.. todo::
+   This is a todo
+
+.. seealso::
+   This is a See Also
+
+Summary
+^^^^^^^
+
+.. seealso::
+
+   * `Sphinx documentation <http://sphinx.pocoo.org/contents.html>`_
+   * `Openalea Sphinx Cheatsheet <http://openalea.gforge.inria.fr/doc/openalea/doc/_build/html/source/sphinx/rest_syntax.html>`_
+
+Building Documentation
+----------------------
+
+The documentation is compiled from the ``.rst`` files during ``make``, but to
+create HTML files from this you will need to run ``make html``.
+
+To see other possible formats run ``make sphinx-help``.
+
+Committing Documentation
+------------------------
+
+Documentation needs to be committed and merged in exactly the same way as
+regular development files.  For more information on this please see the
+:ref:`contributing code <code-label>` page.

=== added file 'docs/contributing/introduction.rst'
--- docs/contributing/introduction.rst	1970-01-01 00:00:00 +0000
+++ docs/contributing/introduction.rst	2011-02-24 15:02:57 +0000
@@ -0,0 +1,39 @@
+Introduction
+============
+
+Drizzle's development primarily happens on
+`Launchpad <http://launchpad.net/drizzle>`_ which handles code hosting, bugs,
+mailing lists and everything else needed for project management.  You will need
+a `Launchpad account <https://help.launchpad.net/YourAccount/NewAccount>`_
+before making most kinds of contributions.
+
+One of Drizzle's aims is to have community contributions valued in the same way
+as core developer contributions, and all code goes through exactly the same
+approval and testing process no matter who it comes from (core developers or
+general community).
+
+There are many ways to contribute to Drizzle, for example:
+
+ * `File a bug <https://bugs.launchpad.net/drizzle/+filebug>`_
+ * `Write translations <https://translations.launchpad.net/drizzle>`_
+ * :ref:`Write documentation <documentation-label>`
+ * :ref:`Write code <code-label>`
+
+We recommend anyone new to Drizzle who wants to learn the code see the `Low
+hanging fruit <https://bugs.launchpad.net/drizzle/+bugs?field.tag=low-hanging-fruit>`_ list of bugs on Launchpad for possible tasks to take on.
+
+Bazaar
+------
+
+Launchpad uses `Bazaar <https://launchpad.net/bazaar>`_ for revision control of
+the source repositories, you will need this insalled before contributing
+documentation or code.
+
+Finding Help
+------------
+
+If you have any questions please contact us at
+`#drizzle <irc://irc.freenode.net/drizzle>`_
+`Freenode <http://freenode.net/>`_ IRC channel or via. the
+`Drizzle Discuss <https://launchpad.net/~drizzle-discuss>`_ mailing list.
+

=== modified file 'docs/include.am'
--- docs/include.am	2011-02-19 18:28:30 +0000
+++ docs/include.am	2011-02-24 15:02:57 +0000
@@ -17,6 +17,7 @@
 	     docs/_static/drizzle.ico \
 	     ${top_srcdir}/docs/*.rst \
 	     ${top_srcdir}/docs/clients/*.rst \
+	     ${top_srcdir}/docs/contributing/*.rst \
 	     ${top_srcdir}/docs/libdrizzle/*.rst \
 	     ${top_srcdir}/docs/installing/*.rst \
              ${top_srcdir}/docs/testing/*.rst

=== modified file 'docs/index.rst'
--- docs/index.rst	2011-02-21 01:35:37 +0000
+++ docs/index.rst	2011-02-24 15:02:57 +0000
@@ -46,6 +46,15 @@
    installing/ubuntu
    installing/redhat
 
+Contributing:
+-------------
+.. toctree::
+   :maxdepth: 2
+
+   contributing/introduction
+   contributing/code
+   contributing/documentation
+
 SQL Language:
 -------------
 .. toctree::

=== modified file 'docs/testing/test-run.rst'
--- docs/testing/test-run.rst	2011-02-23 17:07:17 +0000
+++ docs/testing/test-run.rst	2011-02-24 15:02:57 +0000
@@ -1,3 +1,5 @@
+.. _test-run-label:
+
 **********************************
 test-run.pl - Drizzle testing tool
 **********************************

=== modified file 'docs/uuid_data_type.rst'
--- docs/uuid_data_type.rst	2011-01-14 05:09:22 +0000
+++ docs/uuid_data_type.rst	2011-02-24 15:02:57 +0000
@@ -11,6 +11,6 @@
 
 550e8400-e29b-41d4-a716-446655440000
 
-UUIDs are documented as part of ISO/IEC 11578:1996 "Information technology – Open Systems Interconnection – Remote Procedure Call (RPC)" and more recently in ITU-T Rec. X.667 | ISO/IEC 9834-8:2005. The IETF published Standards Track RFC 4122 that is technically equivalent with ITU-T Rec. X.667 | ISO/IEC 9834-8.
+UUIDs are documented as part of ISO/IEC 11578:1996 "Information technology – Open Systems Interconnection – Remote Procedure Call (RPC)" and more recently in ITU-T Rec. X.667 | ISO/IEC 9834-8:2005. The IETF published Standards Track :rfc:`4122` that is technically equivalent with ITU-T Rec. X.667 | ISO/IEC 9834-8.
 
 Drizzle uses libuuid to generate UUID values.