[mythtv] Comments requested on two bugs

[Gary Buhrmaster]

On Mon, Mar 27, 2023 at 4:26 PM Peter Bennett <pb.mythtv at gmail.com> wrote:

> Thank you Gary for the response.
>
> I looked at the documentation at
> https://www.mythtv.org/wiki/DVR_Service#GetUpcomingList . It shows in
> the example there that the Status is numeric:
>
> <Status>-3</Status>
>
> If I run the API now I get the text description in status in the xml
> format but the numeric value in the json format. That is clearly a bug.
> Today the wsdl shows it it a string. It seems that somewhere along the
> line it was changed from an int to a string but the json version still
> has a number and the documentation was not updated.
>
> So your rule was violated at some point.

Using git, we could determine who introduced
the issue, put as no professional would use
mistakes in the past to justify mistakes in the
future, it mostly does not matter now (so I do
not plan to do the research).

> A question is, what about bug fixes? Do we keep the buggy version around
> because some people are using it that way?

Yes (for buggy versions that have been out
for a while).

I use the Linux approach here, and so should
a project that claims API stability.  Bug fixes
should apply before release (and MythTV
has a long development cycle).  And immediately
after a release (say a month/two) you can
fix a clear mistake that made it into the wild.

After a release (and the mea culpa period)
you are stuck, because you cannot change
user space unless you can show that the
no one could possibly be using the API as
it exists because it does not work (not that
it may work badly, but it cannot be used)
without a long period of deprecation to
allow users to migrate to the new(er) API.

Elements (flags, etc.) can be removed
with sufficient notice (as I said, I would
use V+2 after announcement) as long
as the replacement is in a stable release
so people have time to convert, so if,
for example, the new feature/flags/elements
were released in version N, one can
announce deprecation at the release of
version N, and remove in N+2.

> Another factor is that the version on port 6544 will never be fixed, but
> the version on port 6744 will. Does this count as a new end point? It is
> planned that eventually the code on port 6744 will become the only
> server and its port will change to 6544.

If you are changing user space, it would be
considered a breaking change if the
returned data elements are different
or a different result for the same meaning.

Note that an API *can* start returning
additional elements as part of a "get"/"list"
operation (that would be a compatible
enhancement) as long as it does not
require those elements as part of the
"put"/"update" (i.e. it is tolerant of past
usages without providing those new
elements).  I will note some recent
API improvements have properly done
so (my recollection is that the visibility
and the extended visibility extension
handled that better, so asking Mr. Engle
about what he needed to do to it right
might be useful; as I recall he *did* have
to do a bit more hoop jumping than he
would have done for an API breaking
change), although not all past APIs did
(or may now) do it right

So, if you do not like what element XXX
returns now, add in a XXXv2, and
leave XXX alone, although understand
that a "put" may include only the XXX,
or only XXXv2, or (especially problemantic)
XXX and XXXv2, with only XXX being
changed (which is an artifiact becuase
existing API users know they have to
return all existing values for many
endpoints, even if they did not update
them).

FWIW, API versioning (and pain points)
were discussed back in Dec 2021 when
you asked about API version numbers.
You may still have a copy, or it would
be in this list's archives.  If you cannot
find it I can resend to this list.

Either the API is stable, or it is not.  While
I do care about the choice (I am strongly
in favor of a stable API), it is not my
decision to make, but the project needs to
make a clear decision and then deal with
what that implies for itself, and any users
of the APIs.

Thanks for asking.