The MirageOS Documentation

Agenda

• Quality and Test
• TLS release status
• TCP debugging, profiling and stats
• Documentation best practice

Attendees: Amir Chaudhry (chair), Matthew Gray, David Kaloper, Masoud Koleini, Thomas Leonard, Len Maxwell, Hannes Mehnert, Richard Mortier, Dave Scott, Magnus Skjegstad and Mindy Preston

Notes

Quality and Test

mirge-skeleton — A few people have commented on the list that mirage-skeleton has been broken for them. In addition, there's occasionally confusion about what they should or could do with the content of the repo. Whether what they see there is considered 'best practice', just happens to be there for testing or are snippets for people to use elsewhere.

We believe some of these issues have been fixed via the list but it's worth highlighting when/why this happens. It seems we've set up the master branch of mirage-skeleton to work when using the mirage-dev remote (an opam repository where we stage our releases and work in progress). That means the examples are currently meant to be working with the upcoming releases rather than the packages available in the official repository. Anyone who doesn't expect this is liable to see breakages and probably be confused as to why.

One approach to mitigate this would be to maintain two branches, master and mirage-dev, which would track with the packages in the main opam repo and mirage-dev repo, respectively. This would add a step to the release process, which would involve merging relevant changes from one branch to the other Another approach was suggested, which involves clarifying what it means to have a 'version' of MirageOS (a particular set of libraries).

Regarding the question of what mirage-skeleton is for, we suggested that adding some more information to the repo's README would be helpful.

It was proposed that we continue this discussion either on the mailing list or on an issue on the mirage-skeleton repository. That would allow anyone else to get involved and comment before we make any firm decisions.

TLS release planning

We're gearing up to a release of MirageOS v2.5, which includes support for TLS. While working on this, we uncovered some bugs elsewhere in the stack (TCP) and have been working to resolve them (now being tracked in mirage/mirage#409).

We originally had a fixed date for the news release — to go with the software release — but because of the remaining issues, we're not comfortable making announcements until we're sure the code-base is ready. To relieve some of time pressure and assure a high-quality release, we decided to decouple the different elements as much as possible. Practically speaking, this means we will first get the issues resolved (releasing libraries as usual), then get associated blog posts written, and finally have a news announcement (there's more info in Amir's comment on #409).

A point was raised that we should try and avoid this occurring again, whether that means more testing, or a different process. We asked one of the people present on the call (who shall remain nameless), how his very large and well established company handles things to avoids such release issues ... after a brief pause, the response was "No comment!". So it seems we're no worse than elsewhere but it would be nice to be better.

TCP debugging, profiling and stats

Lots of people have been trying to debug the TCP stack. ThomasG put together a stats branch with extra debug output, which was very useful. However, it slows things down enough that it hides one of the race conditions that ThomasL had uncovered — ThomasL has as issue with TLS on the Cubieboard where it doesn't serve a file.

ThomasL has continued to make improvements to debugging tools and Mindy was very happy about that! These tools will go into the Lwt tracing branch.

It was suggested that one of the effort towards a 3.0 should be improvement of the developer tools around MirageOS, including tracing. This is already one of the elements we've been thinking of while discussing logging but it's worth calling out explicitly. It seems our approach is already a few steps ahead of what other systems provide so it's worth drawing attention to. Our friend in the BigCo did confirm that they're better than the tools he currently uses.

In addition to the above work, Hannes has been working on recoding pcap traces, which is based on Mindy's earlier work. Did point out that TCP needs more hooks to enable this.

Documentation best practice

Dave has been looking at libraries he's been in invovled with and noticed that the documentation could be much improved. Dave was hoping that we could come up with 'best practice' information for how to do docs for code — whether that includes ocamldoc, gh-pages or whatever else. There are also thoughts for how to create tutorials for users, which he'd like to do for certain libs e.g. how-tos for vchan, client/server etc. IOCaml notebooks seem ideal for this and people who've used them rave about them.

After some discussion, we thought it might be good to put together a wiki page with pointers to examples of good practice. We could use this as a guide to raise the quality bar on all libs. Examples to point to could be vchan for the code coverage, cmdliner for docs, etc.

Amir points out that OCaml Labs is looking at improving documentation generation and that there should be some useful tooling out soon (cf. codoc). It would be good to move this discussion to the mailing list so that others can comment and highlight approaches (edit: see the thread on "API documentation best practices").

There were even thoughts that we could construct unikernels, running entirely in the browser and that you can interact with via automatically generated IOCaml notebooks, which would allow people to experiment with the API and talk across browser tabs ... but perhaps not just yet.

--

AoB

• The next call is scheduled for Wednesday, 17th June. Please add any agenda items you wish to discuss in advance and refer to the mailing list for actual details a day or so in advance.