Documentation and guides

Weekly Meeting: 2015-09-30

30th September 2015: Functoria, Irmin plans, numbering and Pioneers

Agenda

Attendees: Reynir Björnsson, Daniel Bünzli, Amir Chaudhry (chair), Justin Cormack, Thomas Gazagnaire, David Kaloper, Thomas Leonard, Anil Madhavapeddy, Mindy Preston, Dave Scott, Magnus Skjegstad, Guybrush Threepwood and Jim Tittlser

Notes

Functoria

See mirage/mirage#441

There's been work towards a new EDSL that's captured in a library called Functoria. We discussed this last time and it needed rebasing due to an earlier .xl patch being merged.

Things have been cleaned up with the patch but it seems there have been some issues with Travis, which someone needs to take a closer look at. Someone also needs to review and test the patch (Anil will do this, feedback from others also welcome). The examples should also be checked over.

One thing we know is still missing as there's an opportunity to retain the shorthand flags we have for --xen and --unix as part of the configure step. ThomasG's not had a chance to look at that yet but would be great to keep them if we can. There's also been some work on related tools we use (cmdliner), to add support for environment variables (dbuenzli/cmdliner@e82fd02).

Aside from the code review, there's already a draft blog post prepared (Amir will review), as well as a note for the breaking changes page of the website (a few things may change for some people).

Getting the IPV6 support in was also blocked on the configuration step too. Once we've completed the releases around Functoria, we can work on getting an IPV6 site up!

Irmin roadmap

There are a number of things we can be doing with Irmin so there's a question of how we decide what exactly what we should work on next. It seems people have lists of things they'd like to get done but pulling these into a clearer plan would be helpful.

ThomasL can compile Irmin to Javascript and then call it from Javascript. It's a bit ugly but can be done and talks more about 'repos' and 'branches' rather than 'stores'. This might be something to make more consistent within Irmin. Would also like to get rid of create and clean up the webserver. Built an Irmin-based webserver but is currently missing the ability to 'push to the server' and 'pull from the server'. You can see the Irmin JS bindings at talex5/irmin-js. ThomasL is still new to Javascript so would be very happy to hear from anyone who can show him a better syntax for the examples. There's an attempt at: https://github.com/talex5/irmin-js/blob/master/examples/tests.js

ThomasG is currently focused on upstreaming patches from work that Mounir did earlier this year (chunking and encryption). This is going well and involves some minimal changes to the API. The main change is a new link store (where you can store links between keys).

There are also improvements to be made on the REST API — which kind of isn't at the moment! It would be great if someone would be able to take look at that. For now, the only users of this are the Go bindings. Given this, perhaps we can look at other REST implementations, then (re)write the bindings with the API we'd like and then modify Irmin.

ThomasL also noticed a lot of memory usage while working with ocaml-git and wondered what might be going on. Amir mentioned that we'd seen this before during work on 'cosmetrics' and Christophe filed issues with test cases (e.g. mirage/irmin#263 and mirage/ocaml-git#125). Any assistance with these would be appreciated!

Although all the above are useful things to work on, the most important thing to solve is the garbage collection, because it hasn't been worked on yet. At the moment it's enough to shell out to git gc but we need to take care about locking and following the Git model properly.

In the short term, ThomasG is making a 0.9.10 release now with some changes and is happy to let ThomasL improve the API beyond that. The next release will have no 1st class modules so a few things will break, including Jitsu. ThomasG will talk to people affected by such changes and support any transitions (this a good reason to add relevant projects to the list of Irmin users. ThomasG then knows who's stuff he might be breaking ☺ )

Version numbering

After the last call, we started a discussion on aspects of release numbering (see the thread). It seems this is a difficult problem to discuss by email as we can't try to solve the general problem.

This discussion came about as we will soon release functoria and a new mirage tool which will introduce a few incompatible changes. Hence we also thought about how we bump version numbers of certain libraries.

Related to this is the question of what it means to have a 'version' of MirageOS, which occasionally crops up. This is complicated by the fact that were talking about a library OS and the libraries necessarily have their own versions — and people can pick and choose what they need for their own purposes. It may be stating the obvious but MirageOS is more than the mirage tool itself, even though this is what people may interact with the most (e.g. it's natural to think of trying mirage --version to find out what you have installed). Having said this, when we've released a collection of new things with new functionality we still label them as 'MirageOS v1.0', 'MirageOS v2.0' and 'MirageOS v2.5' in news announcements and this (broadly) maps to the version of the mirage tool at the time.

Daniel pointed out that we can think of this in two aspects. The first aspect is the API that developers will program against and the second is the tooling around the API. When the the tooling changes, then although some things are affected, it's limited to those parts that make use of that tooling. In this case, the effects on the config.ml files is something that affects the tooling, so isn't a 'major' change. A change in the API would have a wider impact.

This also led to some discussion about how we think of API versions and even whether we should be having one opam package per module type. We still need to think more about these things though.

In the meantime, one suggestion was to adjust the output of mirage --version so that it produces more information about what's installed (perhaps something similar to opam config report). That would be useful to manage the expectations between the mirage tool itself and what we talk about in news announcements. Whatever changes we make need to be thought about, since this output should be readable programatically.

In any case, we should take care to continue to communicate breaking changes clearly as well as putting out release notes.

Pioneer Projects

MirageOS is taking part in Outreachy this year, via Xen Project. A number of people have already been in touch (which is great!) and we've reviewed our project list already. If anyone is interested in a project, please email the list and let us know!

--

AoB