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.
https://gist.github.com/davisp/4013dd3880d3c4ffc600 On Fri, Aug 15, 2014 at 7:44 AM, Paul Davis <[email protected]> wrote: > On Fri, Aug 15, 2014 at 2:10 AM, Benoit Chesneau <[email protected]> wrote: >> On Wed, Aug 13, 2014 at 7:19 PM, Paul Davis <[email protected]> >> 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.
