Re: [MirageOS-devel] Irmin API evolution

[Mindy <mindy@xxxxxxxxxxxxxxxxxxx>]

On 08/10/2015 01:51 PM, Thomas Gazagnaire wrote:
> 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.
I was much more confused by the presence of both APIs than I was by the 
functor version.  I began by using the first-class modules (as the 
instructions/examples encourage) but eventually had to change to using 
functors, and it would've been better to just use the functors from the 
beginning.
> 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)
I think it would be good to either have a terminology that's completely 
different from that which Git uses, or use the Git terminology 
everywhere it's feasible.  The situation where the same words refer to 
different things ("tag" comes to mind) is confusing.
> 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)
Please go ahead and change the API again :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
-Mindy

_______________________________________________
MirageOS-devel mailing list
MirageOS-devel@xxxxxxxxxxxxxxxxxxxx
http://lists.xenproject.org/cgi-bin/mailman/listinfo/mirageos-devel