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
_______________________________________________
Nut-upsdev mailing list
[email protected]
https://alioth-lists.debian.net/cgi-bin/mailman/listinfo/nut-upsdev
