[mythtv] Comments requested on two bugs

Peter Bennett pb.mythtv at gmail.com
Tue Mar 28 20:11:10 UTC 2023


On 3/28/23 11:13, Gary Buhrmaster wrote:
> 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.
> _______________________________________________

It would be better if all replies are in the issue comments, as others 
have done (see https://github.com/MythTV/mythtv/issues/740).

See there for my response.




More information about the mythtv-dev mailing list