Create a maintenance script capable of importing the tool's output

Why we need a maintenance script at all? We can just import it on-wiki.

(In my opinion, the ultimate goal should be no shell users is involved in global election. Local communities can already organize and run its own elections, so I expect global elections be managed by elections committees, not by sysadmins or T&S.)

You mean by pasting the voter list into Voter Eligibility screen? Would probably overwhelm a web interface.

No shell scripts is a good end goal. But in the meantime, I'd be happy with incremental progress. Top priority is not creating 1000 SQL tables per election. Second priority is turning any shell SQL queries into maintenance scripts so that typos are less likely and phpunit tests can be written. Moving it all to a web interface would be far in the future.

You mean by pasting the voter list into Voter Eligibility screen?

Instead the tool can export voter lists to some formats, e.g. CSV (not recommended since there is a potential to mess up user names if the list is manually edited), JSON, XML or even plain text where every line is one username, and SecurePoll will have an interface to upload such files. Or SecurePoll can provide an API, where the Cloud tool can import voter list wiki-by-wiki.

Create a maintenance script capable of importing the tool's output (1 file I assume?) into one SQL table somewhere

It already exists: maintenance/wm-scripts/importGlobalVoterList.php. The tool generates a file with one username per line, consistent with what the maintenance script expects.

Grant Joe access to voterlists.wmcloud.org shell

Joe already has the access.

Joe tries running the tool using the instructions at the readme

Maybe a wikitech page can be created to document how exactly to do it while logged into the VPS node. I'll mention it here for now:

• Log into the machine:
  • ssh YOUR_SHELL_USERNAME@172.16.16.241 -J YOUR_SHELL_USERNAME@bastion.wmcloud.org
• cd /opt/global-election-list-builder
• Create election config file:
  • cd config
  • cp election.template.yaml ucoc-2026.yaml
  • vim ucoc-2026.yaml - edit the file as necessary. The name of the yaml file itself is irrelevant, but the name field in the yaml will be used in valkey key names and in filesystem directory name.
• Run the script:
  • cd /opt/global-election-list-builder
  • screen -S listgen - Start a screen session so that the script continues even if you close your laptop or lose connection
    • ./cli --election config/ucoc-2026.yaml generateList > data/ucoc-2026/logs.out
  • The above command sends logs to data/ucoc-2026/logs.out. Track progress by tailing it.
  • It should take about 3 hours to run.
• Once script run is compete:
  • Grep the log file for ERROR. If nothing, yay!
  • Re-attach to the screen (screen -r listgen) and ensure there are no uncaught errors logged there.
• Final output: data/ucoc-2026/eligible-users.tsv (election name is configured in your yaml file)
  • If you're curious, you can check the number of counted edits for any user across wikis by running:
    • valkey-cli hgetall ucoc-2026:<username>.
      • For each wiki, the value is a string of the form A_B, where A = number of edits in long interval, B = number of edits in short interval.
  • There are other potentially interesting intermediate files in the data directory. But only eligible-users.tsv is the final output.

I'd like to try this for the U4C votes since we have the scripts as backup (T423528). We cannot do so until the cutoff for eligibility on April 24, but after that I'd happily give these steps a try.

In T423547#11828822, @SD0001 wrote:

• ./cli --election config/ucoc-2026.yaml generateList > data/ucoc-2026/logs.out

I don't have permission to create this file it seems:

foks@voterlists-1:/opt/global-election-list-builder$ ./cli --election config/ucoc-2026.yaml generateList > data/ucoc-2026/logs.out
bash: data/ucoc-2026/logs.out: No such file or directory

foks@voterlists-1:/opt/global-election-list-builder$ cd data && mkdir ucoc-2026
mkdir: cannot create directory ‘ucoc-2026’: Permission denied

I also tried just writing to the base dir:

foks@voterlists-1:/opt/global-election-list-builder$ ./cli --election config/ucoc-2026.yaml generateList > ucoc-2026_logs.out
node:fs:1363
  const result = binding.mkdir(
                         ^

Error: EACCES: permission denied, mkdir '/opt/global-election-list-builder/data/ucoc-votes-2026'
    at Object.mkdirSync (node:fs:1363:26)
    at initDataDir (file:///opt/global-election-list-builder/src/utils.js:10:12)
    at Object.callback (file:///opt/global-election-list-builder/src/main.js:83:5)
    at /opt/global-election-list-builder/node_modules/commander/lib/command.js:1517:27
    at Command._chainOrCall (/opt/global-election-list-builder/node_modules/commander/lib/command.js:1489:12)
    at /opt/global-election-list-builder/node_modules/commander/lib/command.js:1516:21
    at Array.forEach (<anonymous>)
    at Command._chainOrCallHooks (/opt/global-election-list-builder/node_modules/commander/lib/command.js:1515:11)
    at Command._parseCommand (/opt/global-election-list-builder/node_modules/commander/lib/command.js:1603:27)
    at /opt/global-election-list-builder/node_modules/commander/lib/command.js:1368:27 {
  errno: -13,
  code: 'EACCES',
  syscall: 'mkdir',
  path: '/opt/global-election-list-builder/data/ucoc-votes-2026'
}

@jrbs You can use sudo su - to become root, which avoids linux file mode issues.