Skip to content

Loading…

adds CONTRIBUTING.md #43

Closed
wants to merge 2 commits into from

2 participants

@emjayess

1st draft commit of @janl's docs contributions content
(http://docs.couchdb.org/en/latest/contributing.html)
as a github project contribution guideline, as per
(https://github.com/blog/1184-contributing-guidelines)


:+1:
The upside to maintaining a bonafide CONTRIBUTING policy file here in the root of the project tree, is that it becomes easily discoverable by folks who arrive at apache/couchdb project on github to open issues and submit pull requests... the policy is revealed thusly above both the "create new issue" and "create new pull request" forms:
Screen Shot 2013-02-21 at 10 56 57 AM

:-1:
The downside is dual-maintenance - keeping this CONTRIBUTING.md policy file in sync with the same content in the share/doc/src/contributing.rst file (plus whereever the source code contribution guidelines are?).

Unless someone knows of a clever way to reconcile that to NOT be dual-maintenance.

@emjayess emjayess adds a CONTRIBUTING.md policy file
1st draft commit of @janl's docs contributions content
(http://docs.couchdb.org/en/latest/contributing.html)
as a github project contribution guideline, as per
(http://docs.couchdb.org/en/latest/contributing.html)
902b5fa
@janl

We could link to contributing.md in the .rst docs.

@emjayess

I guess the other thing to note, is that CONTRIBUTING.md is maintained in markdown, which will be inconsistent with the rst (wiki?) syntax (I've not familiarized to the rst stuff yet, myself). Not sure if this is concerning to anyone, but deserves to be considered.

@janl

@emjayess if we just maintain this file and link to it in the rat docu, we don’t duplicate efforts or run into cross-markup issues.

@emjayess

@janl nod - however I also only just now noticed that github does quite a fine job of rendering the ReStructured Text, so perhaps that could be used instead of traditional github markdown?

Not sure if it requires the .rst extension as a tip-off, and if so, not sure if it would automatically hoist a contributing.rst as the formal policy file. hrrrmmmm.

@emjayess

UPDATE: so i just tried it on another project and github indeed DOES recognize contributing.rst as a bonafide policy file as per above...

so next question: can you move the contributing.rst file from the docs dir to the root, and symlink it back into the docs dir? I probably didn't need to do any of this markdown file fluff.

Do you even want to mix a project-wide contributing policy with one for contributing to docs in the first place?

Sorry for all the questions. #NowWeKnow

@janl

no worries, this discussion itself is helpful.

I don’t know if a symlink will do, but having a
./CONTRIBUTING.rst -> share/doc/src/contributing.rst would be desireable, if the docs build system can cope with it

@emjayess

This can be closed/rejected in favor of a CONTRIBUTING.rst file in root - although the outstanding thing that I'm not sure how to resolve yet is how best to keep a /contributing.rst and /share/doc/src/contributing.rst in sync.

As a refresher, the whole basis for keeping a copy in the project root is that github picks it up and alerts newcomers to the policy for contributing (it's be sweet if @github just allowed a file path to be specified in e.g. project admin).

@emjayess

@nslater-asf did u remark to the effect of potentially changing the format from .rst to something else? I got an email, but not sure what happened to the comment...

@emjayess emjayess closed this
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Commits on Feb 21, 2013
  1. @emjayess

    adds a CONTRIBUTING.md policy file

    emjayess committed
    1st draft commit of @janl's docs contributions content
    (http://docs.couchdb.org/en/latest/contributing.html)
    as a github project contribution guideline, as per
    (http://docs.couchdb.org/en/latest/contributing.html)
  2. @emjayess

    wraps paragraph lines at 72

    emjayess committed
    but not source code lines
Showing with 119 additions and 0 deletions.
  1. +119 −0 CONTRIBUTING.md
View
119 CONTRIBUTING.md
@@ -0,0 +1,119 @@
+# Contributing
+## to Source code
+to be added...
+
+## to 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:
+
+I’m opening the whole CouchDB source tree in my favourite editor. It
+gives me the usual directory listing:
+
+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 http://docs.couchdb.org/en/latest/
+for inspiration. The JSON Structure Reference looks like a fine place
+to write this up.
+
+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
+http://docs.couchdb.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!
Something went wrong with that request. Please try again.