Why do I need to provide my Github login details to add comments?
You need a free Github account to make comments on the book. You will be redirected to Github to login to authenticate to the website. When this is complete, you temporarily grant us access to your public repositories. However, we do not store your authorization tokens on the server side and instead use a client-side cookie on your browser. To log out, simply delete the cookie.
Once authenticated, every paragraph in the book will now have a (comments) link just beside it. Clicking on this link will show you all the comments that other reviewers have made. You can enter your own feedback in there, which will result in an issue being created on the RWO comments repository. This issue will be created using your own Github account, and makes it easier for Anil, Yaron and Jason to follow up with questions.
You will receive e-mail notifications from Github whenever the issue is updated (either with a followup, or just a notification that we've fixed your problem in the next revision of the book).
Do I create a new issue if I want to comment on someone else's comment?
No. If you are browsing comments and you want to start a thread on someone else's comment, then just follow the link marked (github) right beside that particular comment. This will take you directly to the Github issue tracker where you can lodge your feedback.
Why do I need to grant you so much access to the rest of my Github?
Sadly, the Github oAuth mechanism is severely limited in how much access control that we can request. We just want the ability to create issues in one specific public repository, but the minimum privileges we can request from Github are the ones you see when you login. If you can convince someone at Github to add more granular permissions, let us know! However, we never store your authorization tokens in our server, and instead just directly pass your authorization token into a client-side cookie.
Who is Bactrian the Double Humped OCaml, and why does this mysterious ungulate comment on every issue?
We use Github to store all the comments recorded against book milestones instead of keeping our own database. To render the HTML pages, we need to map back every Github issue into a concrete paragraph and milestone id, which is done via the labels associated with every comment in the issue repository. However, the book contents obviously change every milestone, and so we found it convenient to have a bot that uses the OCaml Github bindings to add a contextual link containing the paragraph text to every comment. This lets us (the authors) browse all of the book issues directly using the excellent Github UI, and jump straight to the relevant section in the HTML version of the book if we need to.
Bactrian is a double-humped camel to distinguish us from our single-humped Perl friends. Remember, a dromedary camel has one hump and a bactrian has two (writing the D and the B will help you tell them apart). We're still giddy that we bagged a camel for our book...
What license is the book released under?
The online HTML version of the book is available under a Creative Commons Attribution- Noncommercial-No Derivative Works 3.0 United States License, which means that you are welcome to copy, distribute and transmit the work, but must give us attribution, not create derived works from it, or use it directly for commercial purposes (it's fine to use to within your workplace to learn OCaml, of course, but not to re-sell the book directly.
We'd like to thank O'Reilly for their generosity in allowing this online version to be available freely. Of course, we encourage you to also purchase a copy of the book from them. The O'Reilly production team is doing a tremendous job of typesetting and editing the print version of the book into a beautiful edition that's worthy of a place on your shelf.
Is the source code to the website commenting system available?
It's not right now, but only because the authors are so busy finishing the book. Anil is planning to tidy up the toolchain and open-source it just as soon as he finds time. All the libraries used to build it, such as ocaml-cohttp or ocaml-github are already all available via OPAM.
If you have any questions about all this, please get in touch with Anil Madhavapeddy.