couchdb-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Paul Davis <>
Subject Re: merge, where is the doc?
Date Fri, 15 Aug 2014 14:21:02 GMT
Here's a first pass at things. I'm not entirely sure where this sort
of thing should go in the source tree, suggestions welcome.

On Fri, Aug 15, 2014 at 7:44 AM, Paul Davis <> wrote:
> On Fri, Aug 15, 2014 at 2:10 AM, Benoit Chesneau <> wrote:
>> On Wed, Aug 13, 2014 at 7:19 PM, Paul Davis <>
>> wrote:
>>> Benoit,
>>> I'm not exactly sure what you're asking for here. As I read it, it
>>> sounds like you're wanting documentation both on the merge process
>>> itself and then documentation on all the various things the merge
>>> introduces. As to the merge process, there's really not much to
>>> document other than "import code as agreed, apply patches that were
>>> voted on, fix bugs". The applying of patches and bug fixes its what's
>>> been happening in the windsor-merge branches the last few weeks. If
>>> instead you're wanting documentation on all the things the merge
>>> introduces then you'll have to be more specific on which parts. I
>>> would be more than happy to write documentation for major portions of
>>> the clustering from an internal perspective. I agree that it would be
>>> quite helpful to others that are just starting to learn how this code
>>> works and fits together.
>>> Unfortunately there is no trove of documentation inside Cloudant.
>>> Historically most of our "design" happens over IRC or as code review.
>>> As Bob has said, we obviously can give unrestricted access to our
>>> ticketing system but if there are any patches that are curious we can
>>> go back and get the historical context/reasoning for changes that seem
>>> opaque. On the other hand you seem to be wanting a wider focus
>>> discussion on the various sectiosn of code and how they fit together
>>> of which there really isn't anything at all. But as I mentioned I'd be
>>> more than happy to sit down and write up anything you've got questions
>>> on.
>>> Let me know what I can do to help.
>>> Paul
>> Hi Paul,
>> Thanks for your answer. To be more specific, what could be really useful
>> right now is the following:
>> - layout of the new arch and how apps (and module eventually) interacts
>> - technical description of the consensus algorithm: it would be interesting
>> to have a general overview of the algorithms and how they are used on
>> update/read/query of views
>> - what is the API used to handle the cluster at the lowest level. Imo
>> providing a simple example "ala" riak core would help.
>> - document changes in records, macros and other stuffs done in a doc. A 1.0
>> -> 2.0 doc for devs in short/
>> These points would help anyone that want to help on our code and would also
>> maybe interest the community in general. More eyes we have, the best it is.
>> Among other things i really wish we could do right now is to document all
>> the public internal api we have, put in private others so we could
>> eventually generate edocs. Also having specs defined so we can do more
>> testing and know which data type could be used in a function. This is the
>> hardest to do, so if it could be done on new code it would save a lot of
>> time...
>> For the rest, if full detail can't be given, at least maybe some commits
>> could provide more context. I had an example in mind sometimes ago but I
>> forget. One sure thing for example is that the why of adding couch_event,
>> couch_io could be more detailed in a README.
>> Hope it's more cleat,
>> - benoit
> Benoit,
> That's quite reasonable and something I think we should consider doing
> for all of CouchDB and not just the clustered bits. Some of that I can
> do more quickly than others obviously. I'll try and get a quick write
> up of each app and its main purpose and some of the important modules.
> Some of the other bits will have to wait till I have more time but
> hopefully a quick pass will at least be good enough to give an idea on
> how everything fits together both at the code level and on the
> behavior level.
> BigCouch has fabric which is the clustered API. Beyond that though I
> don't really think that CouchDB has a public API to document. I'd very
> much like to have an API to document though. :D
> I'll try and get something quick written up this morning to at least
> give some general directions on things. Will post back with anything I
> come up with.

View raw message