[mythtv] Services API and Backwards Compatibility

[David Engel]

This is a follow up to the thread I started back in January entitled
"Channel Management Ideas and Plans".  I might be slow but I'm
hopefully persistent. :)

http://lists.mythtv.org/pipermail/mythtv-dev/2019-January/077527.html

I have a patch ready which implements the "never" and "always" values
for channel.visible.  I intend for this change to be included in
MythTV version 31.  I also intend to provide backwards compatibility
in the services API for version 30.

To provide backwards compatibility on reads, the now, legacy variable
named "Visible" still returns a boolean to API clients.  A new
variable named ExtendedVisible returns the real, 4-value enum as a
string to the client.

To provide backwards compatibility on writes, the backend first looks
for the new variable named ExtendedVisible and uses it if present.  If
ExtendedVisible isn't present, the backend looks for the legacy
variable named Visible and tries to use it.

There are some cases dealing with backwards compatibility where the
best behavior isn't obvious.  That is the reason for this email.  I'd
like some feedback on how these cases should be handled before I
commit the patch.

Here are the cases.

Existing Value      Legacy Set      Proposed Result
-------------------------------------------------------
Always Visible      True            Leave as Always Visible (*)
Always Visible      False           Return Error (**)
Never Visible       True            Return Error (**)
Never Visible       False           Leave as Never Visible (*)

(*)The assumption is the user or utility invoking this API call does
not intend to change the value so silently ignore this change.

I originally returned an error for these cases but was persuaded to
change them to the proposed behavior.  The rationale is that the most
common use pattern by a client is to read the current values, make the
desired changes and then send all values back.  Since the legacy value
sent back from the client is the same as the one originally sent to
the client, it's reasonable to assume that no change is intended.

(**)The intent of the new, always/never values is to prevent automated
utilities from changing the value.  User initiated changes should
still be allowed, though.  The backend can't tell who initiated the
API call, however, so return a descriptive error saying why the change
isn't allowed.

A user who got a preview of this change has requested that the
behavior for these cases be changed from returning an error to
silently ignoring the change to channel.visible but honoring all other
changes in the API call.  I don't feel that behavior is correct.  The
user has explicitly enabled the new functionality to prevent such
inadvertent changes.  If such a change is attempted, an error should
be reported so the user can take an appropriate action.

David
-- 
David Engel
david at istwok.net