[Nut-upsdev] Proposal: "experimental" namespace for non-standard NUT variables

[Roger Price]

On Fri, 28 May 2021, Roger Price wrote:
> On Fri, 28 May 2021, Jim Klimov via Nut-upsdev wrote:
>
>>   Looking at NUT pull request (PR) history on GitHub, I see that we have had 
>> a non-trivial number of stalled driver contributions sharing a prominent 
>> similarity: proposed names for some of the variables did not fit into the 
>> list defined at 
>> https://github.com/networkupstools/nut/blob/master/docs/nut-names.txt
>
>>   I propose to add a namespace like "experimental.*"
>
> The future RFC refers to the file nut-names.txt as the "Recording Document" 
> for variable names, thus giving it the authority of the RFC.   It would be 
> useful to clarify this in the introductory paragraph beginning "This is a 
> dump...".  It is more than a dump. The process for adding a variable name to 
> NUT could be formalised under a new heading such as "Process for adding new 
> variable names".
> The text following that heading could then introduce experimental.... 
> variables.

I suggest replacing the first paragraph of the file nut-names.txt with the 
something like the following:

              RFC xxxx Recording Document
              ---------------------------
        NUT variable names and instant commands
        ---------------------------------------

This document is defined by RFC xxxx and referenced as the document of record 
for the variable names and the instant commands used in the protocol described 
by the RFC.

On behalf of the RFC this document records the names of variables describing the 
abstracted state of a UPS, and the instant commands sent to the UPS using 
command INSTCMD, as used in commands and messages between the Attachment Deaemon 
(upsd) and the clients.  Developers should use the names recorded here.

If you need to express a state which cannot be described by any existing name, 
make a request to the NUT developer's mailing list for assignment of a new name. 
Clients using unrecorded names risk breaking at a future update.  If you wish to 
experiment before obtaining your requested variable name, you should use a name 
of the form experimental.x.y

Put another way: if you make up a name that's not in this list and it
gets into the tree, and then we come up with a better name later, clients
that use the undocumented variable will break when it is changed.

NOTE: In the descriptions, "opaque" means programs should not attempt to parse 
the value for that variable as it may vary greatly from one UPS to the next. 
These strings are best handled directly by the user

Roger