15. Contributing to this Documentation

    If you don’t have a GitHub account yet, it is a good time to get one, they arefree. If you don’t want to use GitHub, there are alternate ways tocontributing back, that we’ll cover next time.

    Go to and click the “fork”button in the top right. This will create a fork of CouchDB in your GitHubaccount. If your account is username, your fork lives athttps://github.com/username/couchdb-documentation. In the header, it tells me my“GitHub Clone URL”. We need to copy that and start a terminal:

    I’m opening the whole CouchDB documentation source tree in my favourite editor.It gives me the usual directory listing:

    1. ebin/
    2. ext/
    3. .git/
    4. .gitignore
    5. images/
    6. LICENSE
    7. make.bat
    8. Makefile
    9. NOTICE
    10. rebar.config
    11. src/
    12. static/
    13. templates/
    14. themes/
    15. .travis.yml

    The documentation sources live in src, you can safely ignore allthe other files and directories.

    First we should determine where we want to document this inside thedocumentation. We can look through for inspiration. The JSON Structure Reference looks like a fine place towrite this up.

    The current state includes mostly tables describing the JSON structure (afterall, that’s the title of this chapter), but some prose about the numberrepresentation can’t hurt. For future reference, since the topic in the threadincludes views and different encoding in views (as opposed to the storageengine), 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 – we are in luck, undershare/doc/src we find the file json-structure.rst. That looks promising..rst stands for ReStructured Text (seehttp://thomas-cokelaer.info/tutorials/sphinx/rest_syntax.htmlfor a markup reference), which is an ASCII format for writingdocuments, documentation in this case. Let’s have a look and open it.

    We see ASCII tables with some additional formatting, all looking like thefinal HTML. So far so easy. For now, let’s just add to the bottom of this. Wecan worry about organising this better later.

    We start by adding a new headline:

    1. 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:

    Into:

    1. .. code-block:: erlang
    2.  
    3.     ejson:encode(ejson:decode(<<"1.1">>)).
    4.     <<"1.1000000000000000888">>
    1. Spidermonkey
    2.  
    3. $ js -h 2>&1 | head -n 1
    4. JavaScript-C 1.8.5 2011-03-31
    5. $ js
    6. js> JSON.stringify(JSON.parse("1.01234567890123456789012345678901234567890"))
    7. "1.0123456789012346"
    8. js> var f = JSON.stringify(JSON.parse("1.01234567890123456789012345678901234567890"))
    9. js> JSON.stringify(JSON.parse(f))
    10. "1.0123456789012346"

    into:

    And then follow all the other ones.

    I cleaned up the text a little but to make it sound more like a documentationentry as opposed to a post on a mailing list.

    The next step would be to validate that we got all the markup right. I’llleave this for later. For now we’ll contribute our change back to CouchDB.

    First, we commit our changes:

    1. $ > git commit -am 'document number encoding'
    2. [master a84b2cf] document number encoding
    3. 1 file changed, 199 insertions(+)

    Then we push the commit to our CouchDB fork:

    1. $ git push origin master

    Next, we go back to our GitHub page and click the “Pull Request”button. Fill in the description with something useful and hit the“Send Pull Request” button.

    And we’re done!

    When you make a change to the documentation, you should make sure that youfollow the style. Look through some files and you will see that the style isquite straightforward. If you do not know if your formating is in compliancewith the style, ask yourself the following question:

    If the answer is then it is probably not.

    These guidelines strive be simple, without contradictions and exceptions. Thebest style is the one that is followed because it seems to be the natural way ofdoing it.

    • Encoding

      • All files are UTF-8.

    • Line ending

      • All lines end with .
      • No trailing whitespace.

    • Line length

      • The maximum line length is 80 characters.

    • Links

      • All internal links are relative.

    • Indentation

      • spaces.

    • Titles

      • The highest level titles in a file is over and underlined with =.

      • Lower level titles are underlined with the following characters indescending order:

    1. = - ^ *  + # ` : . " ~ _
    • Over and underline match the title length.

    • Empty lines

      • Lists may separated each item with an empty line.