Re: [PATCH] doc: Add table of MI versions

[Simon Marchi <simon.marchi@polymtl.ca>]

On 2019-01-15 14:19, Eli Zaretskii wrote:
>> 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.

I do not think that is accurate.  Most of the time, we introduce new MI 
functionality without breaking existing usage.  We can do so precisely 
because of what it described in this section.  In particular, that a 
front end should handle gracefully commands and fields it doesn't know 
about.  It's more when we realized we messed up and we must remove or 
change something that is already there, that we break existing usage.

Therefore, I would suggest a little change to your paragraph:

Since @sc{gdb/mi} is used by a variety of front ends to
@value{GDBN}, changes to the MI interface may break 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

I thought this was quite obvious by the fact that we say that we 
introduce a new version when we make breaking changes.  But I can add 
this sentence, which would result in this:

If the changes are likely to break front ends, the MI version level
will be increased by one.  The new versions of the MI protocol are not 
compatible
with the old versions.  Old versions of MI remain available, allowing 
front ends
to keep using them until they are modified to use the latest MI version.

>> >> -@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.

I have opened [1], is it fine to remove the comment from gdb.texinfo?

>> 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?

I don't think we require front ends to use the lowest common 
denominator.  Instead, it should request 
max(version_known_by_the_front_end, version_known_by_gdb).

Simon