Command NameSpace

Status: In Progress

$/!\$ This is a speculative project and does not represent any firm decisions on future behavior.

Introduce official namespaces for commands (like normal, perf, debug, admin, etc…)

1. Goal

Explain what kind of problem are triggering this idea, why it is worth solving and the big picture of how you'll solve it.

As of Mercurial 5.6 we have a few command implicit "namespace"

the "normal" command, that user are expected to touch and were we enforce a strong backward compatibility
the "debug" command, that user are not expected to touch (but that some end up having to) and where we don't provide any backward compat (but end up having to)
the "perf" command, that we use for performance benchmark

The current "debug" namespace is problematic because it mix:

maintenance utility that we point the user at (eg: debugupgraderepo, debugrebuilddirstate)
scripting utility command we need to maintain compatibility with (eg: debugcompletion)
thing we use for test (eg: debugbuildag)
massive footguns that user keep confusing with candies (eg: debugsetparents)

So the idea it to:

Introduce official namespace notation hg namespace-command and "move" command into a limited but meaningful number of namespace.

2. Detailed description

It is important to note that the namespace plan aims at separating command into very high level category (command for users, admin, scrip, mercurial-developer, etc), and is not to be used for more detailled categories (eg: the helpcategory parameters of command, a phab- namespace, etc…). Mixing the two would mud the water and reduce the importance of the semantic barrier between the currently proposed

However, being able to use - in command name would be handy. They could use use for both "soft" namespacing (eg phab-, narrow-, …) and readability (eg: update-cache, upgrade-repo, add-remove, …).

So, should we aims at a different syntax for namespace than the simple group-commandwithnospace ? Here is a couple of idea:

capitalize the group name: eg ADMIN-strip, → quite ugly but effective
double the dash: eg admin--strip, → a bit odd, but with - folding, this is undistinguisable from admin-strip.
using underscore: eg admin_strip, → quite ugly, and the 90th called, they want their _ back
restrict long name to admin/command/test: → This rule out phab- style dash, which is not great.

Current idea for namespace we know we need

"normal": everything things the user should touch, contains most of the current command in that space. (strong BC preserved)
admin-: command that are not meant to be used during "day to day" mercurial usage, but that has legitimate usage for server administration (eg: cache rebuilding) possible other name: maintenance-, tools-
debug-: for debug that nobody should touch unless they are a mercurial developper (no BC preserved)
perf-: for performance command (not structly necessary, but seems useful)

Tentative namespace

script-: for command to be used my script (eg: completion) possible other name: scriputil
exp-: a name space wher we could put experimental command until they behavior start to be backward compatible.
testutil or test for things we use in test only ?
footgun or dangerous for dangerous command (but I woudl rather not have such)

command	possible new namespace	notes
verify	admin
recover	admin
rollback	admin (or maybe footgun)	this one is already (DEPRECATED) (DANGEROUS), but could make sense in that admin namespace
serve	(not really) admin	if we had the namespace for a while and `hg serve` were landing today, it might make sense, but that is a bit late
root	(maybe) script	not really convinced, but playing with ideas. the command is probably fine as it is

command	extensions	possible new namespace	notes
censor	censor	admin
lfconvert	largefile	admin
relink	relink	admin
gc	remotefilelog	admin
repack	remotefilelog	admin
verify	remotefilelog	admin
convert	convert	admin
fastexport	fastexport	admin

command	possible new namespace	new name (namespace syntax not decided)	notes
debugantivirusrunning	admin	admin--is-antivirus-running
debugapplystreamclonebundle	admin	admin--apply-stream-bundle	(Maybe actually not ready to be used)
debugcreatestreamclonebundle	admin	admin--creates-stream-bundle	(Maybe actually not ready to be used)
debugbackupbundle	admin	admin--list-backup-bundles
debugnodemap	admin (part of it)	partially merged in admin--verify (and admin--rebuild-cache?)
debugcheckstate	admin	merged into admin--verify
debugcolor	admin	admin--color-info
debugfsinfo	admin	admin--fs-info
debuginstall	admin	admin--install-info
debuglocks	admin	admin--locks
debugrebuilddirstate	admin	merged into admin--rebuild-cache
debugrebuildfncache	admin	merged into admin--rebuild-cache
debugupdatecaches	admin	admin--rebuild-cache (with flags?)
debugformat	admin	admin--format
debugupgraderepo	admin	merged into admin--format
debugcommands	script	script--complete-command-name
debugcomplete	script	script--complete-command-args
debugnamecomplete	script	script--complete-name
debugpathcomplete	script	script--complete-path

3. Roadmap

get mercurial to automatically fold - in command
define the new syntax
define the new namespaces
move the commands there

CategoryDeveloper CategoryNewFeatures