Add initial development meta-documentation

doc/dev/codestyle.rst

@@ -0,0 +1,52 @@
+Code style conventions
+========
+
+**Note**: As these conventions were established only after a large
+part of the codebase has been written, the code style described here
+is not yet in effect in all parts of the Zotonic code base. We're
+trying to gradually adapt to it, however.
+
+Indenting Erlang code
+---------------------
+
+We use the "Emacs-style" indenting. This indenting style seems to be a
+convention in much of the Erlang world.
+
+Indenting templates
+-------------------
+
+### explain how we do this and how we indent HTML vs. template tags? ###
+
+Spaces versus tabs
+------------------
+
+We use spaces everywhere. One tab stop is equal to 4 spaces.
+
+When writing code, do not introduce trailing whitespace, do not mix
+spaces and tabs and try to keep lines of code shorter than 80
+characters.
+
+
+Writing Commit Messages
+-----------------------
+
+### taken from rebar's readme, https://github.com/basho/rebar; I find those quite sensible. ###
+
+Structure your commit message like this::
+
+  One line summary (less than 50 characters)
+
+  Longer description (wrap at 72 characters)
+
+The summary should be less than 50 characters, and tell what was
+changed. Use the imperative present tense (fix, add, change). For
+example: `Add 'foobar' filter`, `Fix bug in media upload service`.
+
+The description should explain the intention and implementation of
+your approach, in the present tense.
+
+When your commit fixes a bug on github, add `Fixes #1545` on a separate line below the description.
+
+Atomicity
+---------
+Break up logical changes into separate commits. Make whitespace changes separately.

doc/dev/contributing.rst

@@ -0,0 +1,30 @@
+Contributing source code
+=======================
+
+We encourage contributions to Zotonic from the community!
+
+1. Fork the `zotonic` repository on Github (at https://github.com/zotonic/zotonic).
+
+2. Clone your fork or add the remote if you already have a clone of
+   the repository::
+
+     git clone git@github.com:yourusername/zotonic.git
+
+   or::
+
+     git remote add mine git@github.com:yourusername/zotonic.git
+
+3. Create a topic branch for your change::
+
+     git checkout -b some-topic-branch
+
+4. Make your change and commit. Use a clear and descriptive commit
+   message, spanning multiple lines if detailed explanation is needed.
+
+5. Push to your fork of the repository and then send a pull-request
+   through Github::
+
+     git push mine some-topic-branch
+
+6. A Zotonic committer will review your patch and merge it into the
+   main repository or send you feedback.

doc/dev/documentation.rst

@@ -0,0 +1,18 @@
+Contributing documentation
+==================================
+
+For documentation, we encourage contributions to Zotonic from the
+community even more!
+
+
+We use git for documentation. For large documentation changed, you
+should take the same approach as with :doc:`contributing`: e.g. create
+a fork of Zotonic, create a topic branch, make the changes, push, pull
+request.
+
+However, for small changes, typo's, et cetera, Github provides a nice
+edit button which you can use to edit these ``.rst`` files.
+
+**FIXME** -- generate edit links for each RST file!, like this:
+
+`Edit <https://github.com/zotonic/zotonic/edit/master/doc/dev/documentation.rst>`_

doc/dev/filing_issues.rst

@@ -0,0 +1,32 @@
+Filing issues
+=============
+
+Whenever you encounter a bug in Zotonic, please do the following:
+
+* Search the current issue list to see if the bug you're experiencing
+  is already reported.
+
+* If not, search the mailing list and the documentation for
+  references, to see if other people experience the same or if you're
+  the first.
+
+* If you did not find anything, you can file a bug report on github.
+
+
+https://github.com/zotonic/zotonic/issues/new  
+
+In the issues, please state the nature of the problem in a clear and
+reproducible way.
+
+Try summarizing the problem in a single sentence and use that as the
+issue title. In the textarea below, please elaborate on the issue,
+adding the relevant log sections, etc.
+
+Please also state the following:
+
+* Zotonic version you're using
+* Whether you are running zotonic from git or from a downloaded release
+* Operating system
+* Erlang release
+* ... anything that comes to mind that might be relevant, really.    
+

doc/dev/index.rst

@@ -0,0 +1,13 @@
+
+For developers
+=========
+
+Topics:
+
+.. toctree::
+
+   codestyle
+   filing_issues
+   contributing
+   documentation
+

doc/index.rst

@@ -14,6 +14,7 @@ Contents:
    tutorials/index
    manuals/index
    ref/index
+   dev/index
 
 
 Indices and tables