add contributing chapter

3 files changed, 172 insertions, 0 deletions

diff --git a/share/doc/build/Makefile.am b/share/doc/build/Makefile.am
index 3db9689c7..564ae69b9 100644
--- a/share/doc/build/Makefile.am
+++ b/share/doc/build/Makefile.am
@@ -61,6 +61,7 @@ html_files = \
     html/_sources/cors.txt \
     html/_sources/config_reference.txt \
     html/_sources/configuring.txt \
+    html/_sources/contributing.txt \
     html/_sources/ddocs.txt \
     html/_sources/errors.txt \
     html/_sources/http-proxying.txt \
@@ -164,6 +165,7 @@ src_files = \
     ../src/cors.rst \
     ../src/config_reference.rst \
     ../src/configuring.rst \
+    ../src/contributing.rst \
     ../src/ddocs.rst \
     ../src/errors.rst \
     ../src/http-proxying.rst \
diff --git a/share/doc/src/contributing.rst b/share/doc/src/contributing.rst
new file mode 100644
index 000000000..a40d732cd
--- /dev/null
+++ b/share/doc/src/contributing.rst
@@ -0,0 +1,169 @@
+.. Licensed under the Apache License, Version 2.0 (the "License"); you may not
+.. use this file except in compliance with the License. You may obtain a copy of
+.. the License at
+..
+..   http://www.apache.org/licenses/LICENSE-2.0
+..
+.. Unless required by applicable law or agreed to in writing, software
+.. distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+.. WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+.. License for the specific language governing permissions and limitations under
+.. the License.
+
+.. _contributing:
+
+==================================
+Contributing to this Documentation
+==================================
+
+The documentation lives in the CouchDB source tree. We'll start by forking and
+closing the CouchDB GitHub mirror. That will allow us to send the contribution
+to CouchDB with a pull request.
+
+If you don't have a GitHub account yet, it is a good time to get one, they are
+free. If you don't want to use GitHub, there are alternate ways to
+contributing back, that we'll cover next time.
+
+Go to https://github.com/apache/couchdb and click the "fork" button in the top
+right. This will create a fork of CouchDB in your GitHub account. Mine is
+`janl`, so my fork lives at https://github.com/janl/couchdb. In the header, it
+tells me me my "GitHub Clone URL". We need to copy that and start a terminal:
+
+.. code-block: shell
+
+    $ git clone https://github.com/janl/couchdb.git
+    $ cd couchdb
+    $ subl .
+
+I'm opening the whole CouchDB source tree in my favourite editor. It gives
+me the usual directory listing:
+
+.. code-block: shell
+
+    .git/
+    .gitignore
+    .mailmap
+    .travis.yml
+    AUTHORS
+    BUGS
+    CHANGES
+    DEVELOPERS
+    INSTALL
+    INSTALL.Unix
+    INSTALL.Windows
+    LICENSE
+    Makefile.am
+    NEWS
+    NOTICE
+    README
+    THANKS.in
+    acinclude.m4.in
+    bin/
+    bootstrap
+    build-aux/
+    configure.ac
+    etc/
+    license.skip
+    share/
+    src/
+    test/
+    utils/
+    var/
+
+The documentation sources live in `src/doc`, you can safely ignore all the
+other files and directories.
+
+First we should determine where we want to document this inside the
+documentation. We can look through https://couchdb-dev.readthedocs.org/en/latest/
+for inspiration. The `JSON Structure Reference`_ looks like a fine place to write this up.
+
+.. _JSON Structure Reference: https://couchdb-dev.readthedocs.org/en/latest/json-structure.html
+
+The current state includes mostly tables describing the JSON structure (after
+all, that's the title of this chapter), but some prose about the number
+representation can't hurt. For future reference, since the topic in the thread
+includes views and different encoding in views (as opposed to the storage
+engine), we should remember to make a note in the views documentation as well,
+but we'll leave this for later.
+
+Let's try and find the source file that builds the file https://couchdb-
+dev.readthedocs.org/en/latest/json-structure.html -- we are in luck, under
+`share/docs/src/` we find the file `json-structure.rst`. That looks promising.
+`.rst` stands for ReStructured Text (see
+http://thomas-cokelaer.info/tutorials/sphinx/rest_syntax.html
+for a markup reference), which is an ascii format for writing
+documents, documentation in this case. Let's have a look and open it.
+
+We see ascii tables with some additional formatting, all looking like the
+final HTML. So far so easy. For now, let's just add to the bottom of this. We
+can worry about organising this better later.
+
+We start by adding a new headline::
+
+    Number Handling
+    ===============
+
+Now we paste in the rest of the main email of the thread. It is mostly text,
+but it includes some code listings. Let's mark them up. We'll turn::
+
+    ejson:encode(ejson:decode(<<"1.1">>)).
+    <<"1.1000000000000000888">>
+
+Into::
+
+    .. code-block:: erlang
+        
+      ejson:encode(ejson:decode(<<"1.1">>)).
+      <<"1.1000000000000000888">>
+
+And we follow along with the other code samples. We turn::
+
+    Spidermonkey
+
+    $ js -h 2>&1 | head -n 1
+    JavaScript-C 1.8.5 2011-03-31
+    $ js
+    js> JSON.stringify(JSON.parse("1.01234567890123456789012345678901234567890"))
+    "1.0123456789012346"
+    js> var f = JSON.stringify(JSON.parse("1.01234567890123456789012345678901234567890"))
+    js> JSON.stringify(JSON.parse(f))
+    "1.0123456789012346"
+
+into::
+
+    Spidermonkey::
+
+        $ js -h 2>&1 | head -n 1
+        JavaScript-C 1.8.5 2011-03-31
+        $ js
+        js> JSON.stringify(JSON.parse("1.01234567890123456789012345678901234567890"))
+        "1.0123456789012346"
+        js> var f = JSON.stringify(JSON.parse("1.01234567890123456789012345678901234567890"))
+        js> JSON.stringify(JSON.parse(f))
+        "1.0123456789012346"
+
+And then follow all the other ones.
+
+I cleaned up the text a little but to make it sound more like a documentation
+entry as opposed to a post on a mailing list.
+
+The next step would be to validate that we got all the markup right. I'll
+leave this for later. For now we'll contribute our change back to CouchDB.
+
+First, we commit our changes::
+
+    $ > git commit -am 'document number encoding'
+    [master a84b2cf] document number encoding
+    1 file changed, 199 insertions(+)
+
+Then we push the commit to our CouchDB fork::
+
+    $ git push origin master
+
+Next, we go back to our GitHub page https://github.com/janl/couchdb and click
+the “Pull Request button”. Fill in the description with something useful and
+hit the "Send Pull Request" button.
+
+And we're done!
+
+
diff --git a/share/doc/src/index.rst b/share/doc/src/index.rst
index 70d1b9eac..2878a897a 100644
--- a/share/doc/src/index.rst
+++ b/share/doc/src/index.rst
@@ -46,6 +46,7 @@ Contents
     release
     api/reference
     json-structure
+    contributing
     changelog
 
 .. This is how you get a TM sign into a link. Haha. Seriously.