[Lemon-devel] Changes in the lemon repository

[Alpár Jüttner]

Dear Developers,

A decision has been made that we start using a distributed version
control system called Mercurial instead of SVN for the upcoming 1.0
series of LEMON. The next section is a bit longish explanation of why we
decided to change. You can skip it if you want, but please read the last
section shortly describing how these change will be done and how it
affects your work.

* WHY USE DCVS

In the very beginning the LEMON development was done using CVS, but soon
we converted our repository to SVN. More than 3000 commit has been made
since then, and I think we were quite happy with that. However, as we
are now about to start working on the new series of lemon, it seems to
be a good point to review our choice of version control system. 

In fact, SVN has two major shortcomings we have to face from time to
time.

The first and less important is that it cannot be used off-line. In
fact, I must tell you that we managed to live quite well without this
feature in the past several years, so I would consider the off-line
usability as an additional benefit rather than something we must have.

The second problem is much more serious, however. SVN's (and all other
traditional version control system's) basic characteristic is that the
users commit their changes directly into the central repository. Of
course we want to protect the our repository from the unintentional or
malicious changes, so we restrict its write permission. This however
unavoidably divide the people into those are 'insiders' and those are
'outsiders'. This hard differentiation is bad for both side. 
      * For 'outsiders', the only way for contributing into the project
        is to send the changes they made to one of those 'insiders', who
        will review it and then commit these changes into the repository
        under his own name. This is a tedious and error-prone process,
        and it makes no record about the original author. 
      * On the other hand an 'insiders' have unlimited write access to
        the repository. The changes become public immediately before
        anybody could review them. And all of us make mistakes, commit
        something unintentionally, forget to add a file, write a
        misleading commit comment etc. You can find a plethora of
        examples in the lemon svn repository.
Even disregarding these problems, this kind of differentiation is very
bad message towards the potential new contributors. Remember, this is an
open-source project, there should not be second class citizens in the
open-source world.

In order to solve this, distributed version control systems (DVCS) (like
mercurial, git, bazaar and others) introduce a different workflow. Here
a repository can typically be written by very limited number of people,
say by one or two maintainers. However it is easy to duplicate ('clone')
and publish repositories, thus everyone can have its own. Moreover the
'changesets' can easily and safely be exchanged between the
repositories.
Thus the basic workflow can be the following. 
      * Anyone who intend to contribute, first creates a local copy of
        the repository with the full history. Don't worry, this is a
        very fast operation and as easy as issuing a command like
                hg clone http://lemon.cs.elte.hu/hg/lemon-main
      * Then the contributor starts editing the repository and 
                commit her changes into her own _local_ repository in
                the same way as she would do with svn. (hg commit -m
                'Log message')
              * from time to time she also downloads ('pulls')  the new
                changes from the public repository, and merges the
                changesets together. 
      * When she thinks that her changes are of public interest she can
        publish basically in two ways: 
             1. She can send her local commits to the maintainer of the
                main repository. Then the maintainer will review the
                changes and if accepts them, he will insert these
                commits to the main repository. The commits will appear
                there under the name of the original author with the
                full history.
             2. She can also put her own full repository directly to the
                web. Then anyone else will see and be able to use these
                changes immediately. At the same time, she will probably
                send an email to the mailing list about the her new
                changes, or notify the maintainer of the main repository
                directly. Then the maintainer can download the changes
                directly from the contributor's repository and merge
                them to the main one if he wish. 

To sum up, while in SVN the basic operation is 'pushing' the changes to
the central repository, in the DVCS the repositories are typically
maintained by 'pulling' the changes from other (people's) repositories.
And most importantly, doing all of these things are actually much easier
than it seems from this description.

* MERCURIAL - OUR CHOICE OF DVCS

To be short, we examined the three most serious pieces of DVCS software,
namely git, mercurial (hg) and bazaar (bzr). All of the three has more
or less the same capabilities. Git is well known as the version control
system used for the Linux kernel development. Unfortunately it does not
support windows very well and its user interface is fairly complex for
beginners. It also lacks of good documentation. Finally we chose
Mercurial because it has a very nice documentation, easy-to-understand
and logical user interface, and it also seems more matured than bazaar.

*  HOW TO CHANGE TO MERCURIAL

Although it is possible to convert an SVN repository to a Mercurial one,
we decided not to do that, but to simply start a new repository for the
1.x series, while we continue to use SVN for the 0.x series. It means
that 
      * The new repository will not contain the history from before the
        time of the VCS change. This helps us to keep the repository
        compact and free of pollution. 
      * The full history of the files will be accessible in the old SVN
        repository.

This seems reasonable because we plan fundamental changes in the API in
the next series, so the port of code portions from the 0.x series to 1.x
series or vice versa would be more than hard, anyway,

Best regards,
Alpar