Nut upsuser - May 2021 - Proposal: "experimental" namespace for non-standard NUT variables

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.

Roger

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

Thanks Roger for the proposed changes, now they are largely incorporated
into this PR: https://github.com/networkupstools/nut/pull/1046

For the community at large: can I assume everyone with an opinion about
this introduction of "experimental.*" prefix for contributor-defined
concepts in new NUT drivers to fast-track merging of their contributions
(especially where it stalled for months and original authors walked
offline), agrees with such change?

In the coming weeks I hope to go over such stalled PRs (and some recent
merges, e.g. of https://github.com/networkupstools/nut/pull/975) to make
the codebases adhere to the changed standard (by adding the prefix) and so
get more drivers into main NUT tree and less PRs stalled.

It would be very welcome if someone beats me to that and proposes better
names right away before PRs are merged ;)

Some points to look at (there may be some I missed in the cursory search)
include:
*
https://github.com/networkupstools/nut/pull/431/files#diff-acced4571bb1961933a847e91d650ece737286bab496e4875d86b058a7c4606fR461
- nearly all of this mapping table
*
https://github.com/networkupstools/nut/pull/440/files#diff-1b4631911522ab81e231e820b924995818fedb54e89bc7efaf5faee1d2b70c37R228

Jim Klimov

On Fri, May 28, 2021 at 1:09 PM Roger Price <roger at rogerprice.org>
wrote:
> 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
> Nut-upsdev at alioth-lists.debian.net
> https://alioth-lists.debian.net/cgi-bin/mailman/listinfo/nut-upsdev
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL:
<http://alioth-lists.debian.net/pipermail/nut-upsuser/attachments/20210612/de587346/attachment.htm>