couchdb-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Benoit Chesneau <>
Subject Re: merge, where is the doc?
Date Fri, 15 Aug 2014 07:10:05 GMT
On Wed, Aug 13, 2014 at 7:19 PM, Paul Davis <>

> 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

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

  • Unnamed multipart/alternative (inline, None, 0 bytes)
View raw message