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

[Jim Klimov]

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-upsdev/attachments/20210612/de587346/attachment.htm>