#pragma section-numbers 2 <> = Command NameSpace = '''Status: In Progress''' '''Main proponents: [[Pierre-YvesDavid]]''' /!\ 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…) == 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. == Detailed description == ### Which "syntax" 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. ### Which Namespaces ? 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) ### commands by namespace #### Core command || '''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 || ||<#999999> serve ||<#999999> (not really) admin ||<#999999> if we had the namespace for a while and `hg serve` were landing today, it might make sense, but that is a bit late || ||<#999999> root ||<#999999> (maybe) script ||<#999999> not really convinced, but playing with ideas. the command is probably fine as it is|| #### Extension command || '''command''' || '''extensions''' || '''possible new namespace''' || '''notes''' || || censor || censor || admin || || || lfconvert || largefile || admin || || || relink || relink || admin || || || gc || remotefilelog || admin || || || repack || remotefilelog || admin || || || verify || remotefilelog || admin || || ||<#999999> convert ||<#999999> convert ||<#999999> admin ||<#999999>|| ||<#999999> fastexport ||<#999999> fastexport ||<#999999> admin ||<#999999>|| #### debug command || '''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 || || == Roadmap == * (./) get mercurial to automatically fold `-` in command * {X} define the new syntax * {X} define the new namespaces * {X} move the commands there ---- CategoryDeveloper CategoryNewFeatures