Updated Branches: refs/heads/master eb7d91f01 -> 1f5695dd2
add contributing chapter Project: http://git-wip-us.apache.org/repos/asf/couchdb/repo Commit: http://git-wip-us.apache.org/repos/asf/couchdb/commit/1f5695dd Tree: http://git-wip-us.apache.org/repos/asf/couchdb/tree/1f5695dd Diff: http://git-wip-us.apache.org/repos/asf/couchdb/diff/1f5695dd Branch: refs/heads/master Commit: 1f5695dd21fef8801fa267fe4533637cd6ff0f78 Parents: bbd93f7 Author: Jan Lehnardt <[email protected]> Authored: Wed Feb 20 17:08:25 2013 +0100 Committer: Jan Lehnardt <[email protected]> Committed: Wed Feb 20 17:29:41 2013 +0100 ---------------------------------------------------------------------- share/doc/build/Makefile.am | 2 + share/doc/src/contributing.rst | 169 +++++++++++++++++++++++++++++++++++ share/doc/src/index.rst | 1 + 3 files changed, 172 insertions(+), 0 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/couchdb/blob/1f5695dd/share/doc/build/Makefile.am ---------------------------------------------------------------------- diff --git a/share/doc/build/Makefile.am b/share/doc/build/Makefile.am index 3db9689..564ae69 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 \ http://git-wip-us.apache.org/repos/asf/couchdb/blob/1f5695dd/share/doc/src/contributing.rst ---------------------------------------------------------------------- diff --git a/share/doc/src/contributing.rst b/share/doc/src/contributing.rst new file mode 100644 index 0000000..a40d732 --- /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! + + http://git-wip-us.apache.org/repos/asf/couchdb/blob/1f5695dd/share/doc/src/index.rst ---------------------------------------------------------------------- diff --git a/share/doc/src/index.rst b/share/doc/src/index.rst index 70d1b9e..2878a89 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.
