Moving away from master/slave terminology

[MelGrubb]

Let me start by saying that I do not want to start a political war here, and will not be rendering any judgement of the choice of technology terms which predate my time on this planet.

Having said that, there is an industry-wide trend to move away from the terms "master" and "slave". This recently became an issue for me since I cover configuring NUT in a video course I did. As part of a company-wide move toward more inclusive language, the transcript of my course was flagged for re-evaluation and update. I have explained that since I didn't write NUT, there's not much I can do about it apart from injecting an acknowledgement of the troublesome language into the course. It brings up a problem we all may face in a future though, where tools and technology choices may be evaluated and possibly rejected on criteria other than their technical merit.

As a software developer, and part of the IT world, I realize that the terms are an industry standard, and while they may be considered in poor taste in retrospect, they were not chosen specifically to hurt or injure anyone. Having said that, the entire IT industry has started moving in the direction of shedding these terms and replacing them with main/secondary, leader/follower, or server/client where appropriate. Even uses of the term "master" without an associated "slave" such as with git branches or "master recordings", are being frowned on and replaced.

To maintain backwards compatibility, the existing terms will need to be supported, of course, but can additional terms such as primary/secondary or leader/follower be added as synonyms in the configuration system so that people may choose these alternate terms and achieve the same effect?

[clepple]

@MelGrubb Thanks for opening this issue. This has been on my mind for a while, but I think you articulated it better than the draft I was working on.

Part of my dilemma of not publicly raising the issue is related to the gap between the last NUT release and now. We're still getting bug reports from people running 2.7.2 (release six years ago), but we're getting complaints that the latest release (2.7.4) is four years old. I don't want to hold up the next release (which I personally do not have enough time to lead) while we check for unintended side effects of what is ostensibly a simple addition of synonyms. We've already had an embarrassing "just one simple fix" bug (that we know of) while working on the release.

That said, I personally think we do need to pick an alternate set of terms, and even suggest those new terms to users when they upgrade, in order to not propagate master/slave. If NUT were more a part of the "move fast and break things" cult, releasing multiple versions in a year, I think we would be obliged to move more quickly on this. But NUT doesn't move at that pace (and neither do some of its users, judging by the bug reports). In that light, and considering the large number of NUT users and developers for whom English isn't their first language, I hope our apparent inaction until now is not judged too harshly.

I think the renaming of the master branch to main should not be a big deal, but I certainly want to defer to @jimklimov who has been working on the next release. GitHub info is here: https://github.com/github/renaming#later-this-year-seamless-move-for-existing-repositories-

If anyone has strong opinions for new names, please add them below.

[MelGrubb]

Renaming Git branches it's actually very easy. The trouble is getting everyone on the same page so that the old master doesn't keep getting resurrected. As long as someone is the gatekeeper, taking PRs, and not just letting people commit to master, it shouldn't be a problem. I've done it on a smaller team project.

…

---- On Oct 31, 2020 4:36 PM, Charles Lepple <[email protected]> wrote: @MelGrubb Thanks for opening this issue. This has been on my mind for a while, but I think you articulated it better than the draft I was working on. Part of my dilemma of not publicly raising the issue is related to the gap between the last NUT release and now. We're still getting bug reports from people running 2.7.2 (release six years ago), but we're getting complaints that the latest release (2.7.4) is four years old. I don't want to hold up the next release (which I personally do not have enough time to lead) while we check for unintended side effects of what is ostensibly a simple addition of synonyms. We've already had an embarrassing "just one simple fix" bug (that we know of) while working on the release. That said, I personally think we do need to pick an alternate set of terms, and even suggest those new terms to users when they upgrade, in order to not propagate master/slave. If NUT were more a part of the "move fast and break things" cult, releasing multiple versions in a year, I think we would be obliged to move more quickly on this. But NUT doesn't move at that pace (and neither do some of its users, judging by the bug reports). In that light, and considering the large number of NUT users and developers for whom English isn't their first language, I hope our apparent inaction until now is not judged too harshly. I think the renaming of the master branch to main should not be a big deal, but I certainly want to defer to @jimklimov who has been working on the next release. GitHub info is here: https://github.com/github/renaming#later-this-year-seamless-move-for-existing-repositories- If anyone has strong opinions for new names, please add them below. —You are receiving this because you were mentioned.Reply to this email directly, view it on GitHub, or unsubscribe.

[jimklimov]

Github's documentation does suggest waiting until they make the branch renaming seamless (e.g. with regard to many open PRs, like we have so far), so that seems a reasonable point to wait a bit and avoid resurrecting the branch name by merging stuff. A "main" branch name seems neutral enough to accept, until some next wave of protests claims that all should be equal and none more equal than others.

Alias keywords and docs changes probably should not be too intrusive and might be a welcome bit of a new release actually - if someone does the PR with changes and they do work... especially if our cadence happens to be so infrequent lately, that we'd otherwise be officially stuck with terminology that suddenly hurts someone's ears for some more years :(

My own opinion on this is mixed and not worth discussing here, suffice it to say there are no direct technical merits and a possibility of breaking something. But also a reason for revisiting rarely seen parts of code and finding bugs by chance, which could end up useful ;) And probably social merits.

So on balance, we should eventually flow with the crowd, just not sure it ranks high in priorities of core team members compared to other release blockers.

[biergaizi]

Alias keywords and docs changes probably should not be too intrusive and might be a welcome bit of a new release actually

What would be the scope of such changes? Renaming keywords and docs shouldn't be too difficult, but what about internal code? Unfortunately, sometimes the terminology comes from the external world that is beyond our control. Changing it can potentially create confusions (when it's defined by protocols or datasheets), or even impossible (when it's defined by the external libracy).

For example, on the Huawei UPS2000 driver that I'm working on (since the current consensus is to gradually move away from such terminology, albeit at low priority, I obviously don't want to introduce more to the codebase, however...), there are numerous references to MODBUS_SLAVE_ID and modbus_set_slave() throughout the code. I didn't invent the terms - one is defined by the protocol, and another is an external library function in libmodbus, which is beyond our control.

I2C has the same problem.

# egrep "SLAVE|slave" *.c | uniq
asem.c:#	include <linux/i2c-dev.h> /* for I2C_SLAVE */
asem.c:	if (ioctl(fd, I2C_SLAVE, address) < 0) { \
pijuice.c:#	include <linux/i2c-dev.h> /* for I2C_SLAVE */
pijuice.c:	if (ioctl(file, I2C_SLAVE, addr) < 0)
...

I2C_SLAVE is defined by the Linux kernel, which is not something that can be changed unilaterally.

Same for SNMP, "master/slave" is the official terminology used in the protocol.

snmp-ups.c:		/* Only append "device.X" for master and slaves, if not already done! */
snmp-ups.c:				/* Device(s) 1-N (master + slave(s)) need to append 'device.x' */
snmp-ups.c:					/* Device(s) 1-N (master + slave(s)) need to append 'device.x' */
snmp-ups.c:			/* Device(s) 2-N (slave(s)) need to append 'device.x' */
snmp-ups.c:	 * connectivity to; the current_device_number > 1 is a slave (chained by
snmp-ups.c:	 * through the master - the slaves are not addressable directly. If the
snmp-ups.c:			// default: devtype = "daisychain slave"
snmp-ups.c:					(current_device_number == 1)?"master":"slave"); // FIXME: daisychain

On the other hand, currently there is only one Modbus driver (if my patch is accepted, two Modbus drivers), two I2C drivers, and one SNMP driver in the code base, so I wouldn't say it's a big problem.

[jimklimov]

I suppose as far as the social aspect is concerned, the visible terms (docs, messages, config keywords) matter most. People digging in code are usually more tolerant.

…

On Wed, Jan 6, 2021, 11:12 #DeleteGithub ***@***.***> wrote: Alias keywords and docs changes probably should not be too intrusive and might be a welcome bit of a new release actually What would be the scope of such changes? Renaming keywords and docs shouldn't be too difficult, but what about internal code? Unfortunately, sometimes the terminology comes from the external world that is beyond our control. Changing it can potentially create confusions (when it's defined by protocols or datasheets), or even impossible (when it's defined by the external libracy). For example, on the Huawei UPS2000 driver that I'm working on (since the current consensus is to gradually move away from such terminology, albeit at low priority, I obviously don't want to introduce more to the codebase, however...), there are numerous references to MODBUS_SLAVE_ID and modbus_set_slave() throughout the code. I didn't invent the terms - one is defined by the protocol, and another is an external library function in libmodbus, which is beyond our control. I2C has the same problem. # egrep "SLAVE|slave" *.c | uniq asem.c:# include <linux/i2c-dev.h> /* for I2C_SLAVE */ asem.c: if (ioctl(fd, I2C_SLAVE, address) < 0) { \ pijuice.c:# include <linux/i2c-dev.h> /* for I2C_SLAVE */ pijuice.c: if (ioctl(file, I2C_SLAVE, addr) < 0) ... I2C_SLAVE is defined by the Linux kernel, which is not something that can be changed unilaterally. Same for SNMP, "master/slave" is the official terminology used in the protocol. snmp-ups.c: /* Only append "device.X" for master and slaves, if not already done! */ snmp-ups.c: /* Device(s) 1-N (master + slave(s)) need to append 'device.x' */ snmp-ups.c: /* Device(s) 1-N (master + slave(s)) need to append 'device.x' */ snmp-ups.c: /* Device(s) 2-N (slave(s)) need to append 'device.x' */ snmp-ups.c: * connectivity to; the current_device_number > 1 is a slave (chained by snmp-ups.c: * through the master - the slaves are not addressable directly. If the snmp-ups.c: // default: devtype = "daisychain slave" snmp-ups.c: (current_device_number == 1)?"master":"slave"); // FIXME: daisychain On the other hand, currently there is only one Modbus driver (if my patch is accepted, two Modbus drivers), two I2C drivers, and one SNMP driver in the code base, so I wouldn't say it's a big problem. — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#840 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAMPTFF5RKO34ENOW7TMBNLSYQZR5ANCNFSM4TBSKKUA> .

[jimklimov]

Quoting from the mailing list discussions started about this at

• https://alioth-lists.debian.net/pipermail/nut-upsuser/2021-March/012359.html
• https://alioth-lists.debian.net/pipermail/nut-upsdev/2021-March/007523.html

---

For now I've prepared draft PRs, mostly to map out where the changes are needed - based on my earlier work with the originally proposed terminology.

Now that we know where to change it, should not be too great a hassle to replace again by some other choice... subordinate was a bit too long to type - although this is now behind me :)

To make the election of team choice more simple, I have prepared my first SurveyMonkey poll here - it should be possible to choose one response for each of the two roles (although if you really can't pick one of several names you like, you should be able to take the poll again):

• https://www.surveymonkey.com/r/GBHQM7Q

Changes related to upsmon, and bookmarks for protocol "MASTER" keyword, are PRed here:

• Retire some terminology #992

Also some nearby paragraphs in the docs were updated and extended, which I extracted into separate PRs - reviews welcome:

• Docs update and clarification #989
• Easy fixes for issue #840 #990
• docs/developers.txt: replace "master" where it is easy… #991

[jimklimov]

In the end, after a couple of weeks we had 18 votes on the survey with clear leaders: "primary" and "secondary" both gathering 7 votes as replacements of "master" and "slave" respectively. PR #992 is being updated to reflect the popular choice.

Runner-ups: "Manager" was half as popular (3 votes) for the first question, and "Subordinate" and "Agent" each had 2 votes for the second question. Keeping the old terminology per "Other" answers had at least 4 votes for each (modulo variations in typing).

[jimklimov]

It was decided to currently draw a line with these PRs to constrain them to documentation changes (and related change to upsmon to accept the new keywords along with old ones). Points where to look when we decide to alter the protocol and/or API were mapped and commented, but such changes will need more thorough review and testing and so would take longer to get into the codebase.

One useful discussion proposed to mark deprecated routines with attributes (where compiler support for those is detected) so third-party code linking against NUT would be able to modernize as well: #992 (comment)

[jimklimov]

One more point also not handled at the moment is an update of images in the documentation (texts refer to some), to reflect new wording.

UPDATE: done

[jimklimov]

Some testing would be good; but there were no complaints about regressions so far at least.

[jimklimov]

UPDATE: Testing for "primary" in place of "master" for monitoring of an "all-in-one" system (driver+upsd+upsmon on same localhost) was successful. Example configs involved:

# cat /usr/local/ups/etc/upsd.users
[nutmon]
    password = Tr@kster
    upsmon primary
    actions = SET
    instcmds = ALL

# cat /usr/local/ups/etc/upsmon.conf
#debug_min 3
MONITOR nutdev1 1 nutmon "Tr@kster" primary
MINSUPPLIES 1
SHUTDOWNCMD "/bin/echo UPS-OOPS | /usr/bin/wall"
POLLFREQ 5
POLLFREQALERT 5
HOSTSYNC 15
DEADTIME 15
POWERDOWNFLAG /etc/killpower

[jimklimov]

Similar change for protocol (to support both key words, and prefer PRIMARY <ups> request in newer builds, fall back to MASTER <ups> if old client talks to new server or old server replies to new upsmon) implemented in #1328

[chocmake]

Just thought I'd note that Raspberry Pi OS (Legacy x64 Lite at least*) only installs the v2.7.4 version of NUT (from 2016) when the nut packages are installed via the commonly suggested apt package manager.

This only becomes more obvious after installing it when viewing say certain SSH console messages but the upshot is that all the online docs now use the primary/secondary terminology while many users are likely unwittingly having older NUT packages installed on their Pis, which only support the master/slave terminology. The inline config comments do use the old terminology though.

This caught me out on my Pi since I wondered why the new terminology wasn't working, until noticing only older packages are installed via apt for unknown reasons.

* The official Pi Imager program exclusively lists Legacy only OS versions for Pi Zeroes, apparently for stability reasons. They're still kept up to date though. Afaik Legacy is based on Debian 'Buster' (from 2022).

[xkszltl]

You may also wanna suggest to other popular doc source about this change.
For example, Debian wiki still uses master, despite Debian 12's nut is using primary/secondary.

• https://wiki.debian.org/nut

[jimklimov]

Thanks, for the heads-up!

FWIW, this was in the UPGRADING (and more detailed NEWS) docs which package maintainers and others who update are supposed to read. We know of a dozen or two distros that ship NUT, maybe might contact them explicitly but did not for whatever reason (though some pkg maintainers are/were on mailing list, so saw no need). We would never know about ALL distros there are though, so it is really their homework :)

Also just in case, the older terms are deprecated but should still work, probably indefinitely.