Repo based version numbering

[Alpár Jüttner]

On Mon, 2008-11-10 at 13:48 -0600, Matt Mackall wrote:
> On Mon, 2008-11-10 at 15:01 +0000, Alpár Jüttner wrote:
> > >       * I haven't dig into the Mercurial API deeply enough. :) As you
> > >         can see in the history, I've just changed the code to use the
> > >         API instead of just executing 'hg log --template{}' and parsing
> > >         the result.
> > 
> > BTW, how much can I rely on the stability of the Mercurial API? Is there
> > any official statement on this?
> 
> Yes: there is no stable API. We will break interfaces that present a
> barrier to improving the core code without regard for its impact on
> third party extensions. If you want guaranteed stability, use the
> command line interface.

You advertise Mercurial as the fastest DVCS. I would like to enjoy this
advantage. Changing from using CLI to API allowed me speed up the
longest path calculation from 2.4s to 0.7s. And this is an important
improvement as the stupid autoconf calls the version computing script
several times. But it is also important for me to make sure that my
library will compile on various platform.

> Realistically, any software project that isn't effectively dead is going
> to break its APIs from time to time to keep from collapsing under the
> weight of its own past mistakes.

For me, it is a bit strange. The CLI provide an interface to the core
for shell users. The API provide an interface to the core for Python
users. What is the substantial difference?

If you require CLI stability, you must also carry on the "past
mistakes", which indeed happens sometimes. For example the odd meaning
of '-r' in 'hg status' or the different parameter style of 'hg export'
and 'hg bundle'.

(BTW, I would even relax on CLI stability a bit. Namely, I would allow
changing the output of the mercurial commands, and would kindly ask the
script writers to use --template all the time.)

But in general, any kind of interface stability is not from the evil for
me, but a natural requirement. I understand it can cause problems _in
the long run_.
Thus, I prefer the approach that ensures the stability of a well defined
public part of the code (for me this is the Application Programming
Interface of a library) in the minor releases, but allows arbitrary
changes between major releases.

> If you want an SCM with a
> stable API, use CVS.

Is it a joke? Or did my question make you angry? If yes, I apology.

> In practice, such breakage is very minor. When we make a change to the
> core, we also update all the extensions in hgext/ and that usually takes
> no more than a couple minutes.

That is nice. I see that the changes are typically minor, it was trivial
in my case, too. And this approach is indeed satisfactory for the
extensions bundled with Mercurial. But causes some problem with third
party extensions, and a major obstacle if someone just want to write a
simple but stable repository maintenance script in Python.

Best regards,
Alpar