Documenting MI stability (Was: MI -break-info command issues)

[Vladimir Prus <ghost at cs dot msu dot su>]

On Friday 27 January 2006 19:13, Bob Rossi wrote:
> On Fri, Jan 27, 2006 at 07:09:56PM +0300, Vladimir Prus wrote:
> > Daniel Jacobowitz wrote:
> > >> The problem with existing frontends can probably be solved by posting
> > >> a prominent message to mailing list whenever MI output is going to
> > >> change. Or using versioning.
> > >
> > > This has been discussed before plenty of times.  We will make
> > > incompatible changes to MI from time to time; but IMO that doesn't
> > > justify making _unnecessary_ incompatible changes.
> > >
> > > Like Bob, I wouldn't have added the fields.  But since they are
> > > present, I see no reason to remove them.
> >
> > Ok, understood. It would be good, though, if MI docs contained some
> > introduction chapter that would state this policy. That'd prevented this
> > thread from ever starting.
>
> Hi Volodya,
>
> It would be great if you could come up with some text that described the
> problem. We could improve it here, and then add it to the manual.

Hi Bob,

What about this:

    = Stability =

    While MI format is still evoling, all changes to it will be backward
    compatible. That is, only new fields will be added, and all existing
    fields will be retained. 

    This means that replies to certain command might contain information that
    is not strictly necessary for machine interface, and a present for
    historical reasons only.

    Rationale: There are many MI frontends around, and their developers don't
    necessary follow MI changes and read the mailing list, so it's better
    to live with a few extra fields than risk breaking existing code.

You probably can phrase this better, but something to this effect will be a 
good addition to MI manual. And it would be great to have some guidelines 
when MI compatibility *can* be broken -- I don't know those guidelines so 
can't write anything about it.

Thanks,
Volodya