On Fri, Aug 15, 2014 at 2:10 AM, Benoit Chesneau <bchesn...@gmail.com> wrote: > On Wed, Aug 13, 2014 at 7:19 PM, Paul Davis <paul.joseph.da...@gmail.com> > 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.
