On Sun, Oct 20, 2024 at 4:24 PM Tim Starling tstarling@wikimedia.org wrote:
On 26/9/24 13:10, Reuven Lazarus wrote:
Starting a maintenance script looks like this:
rzl@deploy2002:~$ mwscript-k8s --comment="T341553" -- Version.php --wiki=enwiki
Any options for the mwscript-k8s tool, as described below, go before the --.
After the --, the first argument is the script name; everything else is passed to the script. This is the same as you're used to passing to mwscript.
Is that a limitation of Python's command line parsing?
I mean, the obvious way to do it from the viewpoint of usability is to take options after the first argument as belonging to the script.
No, this was a design choice. There are a few different ways to set up the interface, but each has different usability drawbacks.
(This has the potential to consume the thread; I'd prefer if it didn't, even though I appreciate the feedback! Happy to chat more about it off-list, or discuss a feature request as a subtask of T341553 https://phabricator.wikimedia.org/maniphest/task/edit/form/1/?parent=341553&template=341553&status=open&subscribers= .)
The usability problem with the current approach is the extra --. It requires extra space and typing, it's easy to forget, and it's an extra thing for new users to learn. That's especially salient right now as everyone's a new user.
The usability problem with splitting at the script name is that it makes the parsing of non-positional arguments sensitive to their order, which is surprising. That is,
$ mwscript-k8s --verbose script.php $ mwscript-k8s script.php --verbose
would mean different things, which isn't what that option syntax usually indicates. (In the first, --verbose modifies the behavior of the mwscript-k8s wrapper, printing extra information about the process of launching the Kubernetes job. In the second, it modifies the behavior of the maintenance script.)
When you're lucky, one will work and the other unexpectedly won't; when you're unlucky, they'll both work but the behavior is unexpected. A similar issue already surprises people with mwscript as it exists today (most recently six days ago, https://phabricator.wikimedia.org/T372337#10231006). mwscript-k8s doesn't change that, since it's a function of MaintenanceRunner.php -- and shouldn't change it, since scripts like dumpBackup.php are sensitive to the order -- but this was an intentional decision not to add a second layer of order sensitivity. Instead we're sensitive to "before or after the separator," which is explicit, visually distinctive, and a familiar standard.
Other interface options (wrap the script and its args in quotation marks; let mwscript-k8s consume any options known to it, and pass the rest through to the maintenance script; use no command-line options at all for mwscript-k8s, just control it with environment variables) were rejected for other usability problems. (Most of the problems are self-evident, like being annoying to type. The consume-known-options approach is attractive when everything works well, but it has problems when names collide, like if both mwscript-k8s and the script have a --verbose; it also handles typos ungracefully.)
Python's built-in parsing isn't really a limiting factor, we can do whatever we want. After spending time thinking about it, this looked like the best choice, but I'm open to other ideas. :)