[MirageOS-devel] Irmin API evolution

[Thomas Gazagnaire <thomas@xxxxxxxxxxxxxx>]

Hi all,

There are still parts in the Irmin API that I am not very happy about, so I 
send an email to get feedback from all the early users to check if they share 
my views.

1. The functor / first-class module interfaces: the first-class module is 
simpler to grasp, it is harder (or sometimes impossible) to do more complex 
tasks with them. A lot of people have reported to me that it's confusing and 
that it's bad to duplicate the API. I agree and I propose to remove the 
first-class module API all together and add one or two default higher-level 
functors to simplify a little bit the current functor API.

2. The View API is mutable, although it would be better to make it 
immutable[1]. Views keeps a list of operations which are been applied to it 
(such as reads) so merging a view is similar to committing a transaction in 
usual DB context. I think it is hard to keep the same behaviour on immutable 
views without being too verbose or confusing. So I propose to rename View to 
Transaction and have a proper immutable Staging area.

3. The terminology is slightly different that the usual Git one. I think it is 
better to change it to match exactly to help people already knowing Git to 
start with Irmin more easily (eg. Irmin's tag are Git's references, Irmin's 
heads are Git's commits, etc)

4. The Irmin API conflates the Git repository configuration and branch state 
into an Irmin store handler. For some operations (as listing all the branches 
in a repository) it doesn't make really sense. Maybe it's too confusing and you 
don't want that. See Cuekeeper'API[2] which exposes a different API, closer to 
what Git offers. Also, Irmin offers 3 ways to create a new store handler: using 
the master branch, using a given branch name, or using a commit id. Only using 
a commit id is fully "concurrency-safe" unless you know exactly what you are 
doing -- this is not very clear in the API and can be surprising to users. We 
should change that.

So in the very short-term (read this week or the next) I plan to release a 0.10 
API with at least:
- deletion of the 1st class module API (address 1.)
- some renaming of modules (at least Tag -> Reference, View -> Transaction, 
type head -> type commit, etc...) 
- addition of an immutable staging area (address 3.)
- and something (not clear yet) to address 4.

I am very interested to get feedback on this, so please reply if you are or 
were (or will be) using Irmin at one point ("please don't change the API again" 
is also a good reply :p)

Best,
Thomas

[1]: https://github.com/mirage/irmin/issues/109
[2]: https://github.com/talex5/cuekeeper/blob/master/utils/git_storage_s.ml
_______________________________________________
MirageOS-devel mailing list
MirageOS-devel@xxxxxxxxxxxxxxxxxxxx
http://lists.xenproject.org/cgi-bin/mailman/listinfo/mirageos-devel