[PATCH] doc: Add table of MI versions

[Eli Zaretskii]

> Date: Tue, 15 Jan 2019 13:27:37 -0500
> From: Simon Marchi <simon.marchi@polymtl.ca>
> Cc: Simon Marchi <simon.marchi@ericsson.com>, gdb-patches@sourceware.org
> 
> >> -Although @sc{gdb/mi} is still incomplete, it is currently being used
> >> -by a variety of front ends to @value{GDBN}.  This makes it difficult
> >> -to introduce new functionality without breaking existing usage.  This
> >> -section tries to minimize the problems by describing how the protocol
> >> -might change.
> >> +The MI interface is versioned, allowing it to evolve while avoiding 
> >> breaking
> >> +existing front ends.
> > 
> > Some of the rationale you removed sounds like something good to have.
> > Explaining the rationale for a section is in general a Good Thing,
> > IMO.
> 
> The "is still incomplete" sentence sounds useless to me, and can even 
> make people wonder if they should really use it, since it's incomplete.  
> It will always evolve, it will never be "complete".  I could add back 
> the last sentence with a bit more stuff, like so:
> 
> The MI interface is versioned, allowing it to evolve while avoiding 
> breaking existing front ends.  This section describes how the protocol 
> might change within a version and the breaking changes across versions.

The part about MI being incomplete is not what I wanted to preserve.
How about something like this:

  Since @sc{gdb/mi} is used by a variety of front ends to
  @value{GDBN}, introduction of new MI functionality almost always
  breaks existing usage.  This section describes how the protocol
  changes and how to request previous version of the protocol when it
  does.

> >>  If the changes are likely to break front ends, the MI version level
> >> -will be increased by one.  This will allow the front end to parse the
> >> -output according to the MI version.  Apart from mi0, new versions of
> >> -@value{GDBN} will not support old versions of MI and it will be the
> >> -responsibility of the front end to work with the new one.
> >> +will be increased by one.  Previous versions of MI remain available, 
> >> allowing
> >> +front ends to keep using them until they are modified to use the 
> >> latest MI
> >> +version.
> > 
> > Likewise here: the old text explained that miN version will generally
> > be incompatible with miN-1 version.  Your change removes that
> > important statement.  I'd prefer not to lose that part.
> 
> Which part of the original text says that?

This one:

  [...] new versions of @value{GDBN} will not support old versions of
  MI.

Which is actually slightly confusing; a better way of saying that is
something like

  new versions of the MI protocol are not compatible with the old
  versions

> What I want to say is that even if a new version of MI is 
> released, the previous versions of MI stay available for some time, 
> allowing front ends to do the transition.

That's okay, but it's a separate issue.  Let's keep the other
information as well, as suggested above.

> >> -@c Starting with mi3, add a new command -mi-version that prints the 
> >> MI
> >> -@c version?
> > 
> > Why did you remove the comment?  It seems like a valid idea, perhaps
> > worth implementing.
> 
> I don't think this is the right place for such things (it's quite 
> hidden).  If we really want to keep track of this, let's open an issue 
> on Bugzilla for it.

I'm fine with moving this to bugzilla, I just don't want to lose the
suggestion altogether, as part of unrelated changes on top of that.

> About the idea itself, I don't think we need to implement this.

We don't need to agree with it, we just need to preserve the
suggestion.

> If front ends request a specific version of MI (which is good
> practice, in my experience), they won't need to query it.

What if a front end can support several versions, provided that it
knows the latest version which is provided?  Why require such a front
end to request the lowest common denominator, instead of adapting to
the latest version it can support?

Thanks.