Theia: Command Label Conventions

[svenefftinge]

I'd like to introduce the following conventions regarding command labels:

• Prefix with the short name of the extension, followed by a colon, e.g. Git: Push.
• Suffix with ..., if the command asks for additional input, e.g. Git: Merge....

To fix this issue, we need to agree and do the following:

• [ ] Update all command labels
• [ ] add this guideline to the docs

[svenefftinge]

Please note, that this is not about menu items, which might omit the prefix if they are shown in a clear context. E.g. in the git view, it is fine to name the actions Push and Merge....

[kittaakos]

@svenefftinge, what is the truth? Something... or Something ... I can see both in the application.

+1 for no whitespaces between the label and the ellipses.

[AlexTugarev]

Spaces around ellipsis should be the same as inside. No space before ..., if it's not following a comma, cf. apple main menu.

[svenefftinge]

Yes, no space.

[epatpol]

The problem is, as @svenefftinge mentionned I think? If we change something to like Git: History it will look good in the command palette but weird in the menu. We could add an optional label to the Command interface like menuLabel or something?

[kittaakos]

We could add an optional label to the Command interface like menuLabel or something?

One can customize the menu label like this. We did that exactly for in the Git extension.

[epatpol]

I'd like to do it as I remember not being sure what label to add to new commands. I suggest we do not add that prefix to Monaco/Editor and Core commands, maybe Workspace too? Maybe Editor: Copy is a bit overkill ? Although I'm always okay with things being more verbose than not. Looking at vscode's command palette it seems Git and other extensions/packages that provide several commands have that prefix, but not core commands.

Also what about commands like Open New Terminal, do you think Terminal: Open New One or just Terminal: Open is good enough?

[kittaakos]

do you think Terminal: Open New One or just Terminal: Open is good enough?

:) or Terminal: Open New?

[svenefftinge]

This needs more fine tuning or needs to be softened. Some general requirements are

• If a label is shown in a certain context (i.e. context menu of a widget), it can be shorted (omitting that obvious context information). E.g. Merge... instead of Git: Merge...
• If it is shown in a global place (command palette, main menu) it needs to be clear what it does.
• This is not about 'extension' names but about telling the user what a command does, as well as using consistent terminology
• In some cases it seems to be a good pattern to prefix the context, like in Git: Merge... but Terminal: Open is IMHO not better than Open Terminal.

Given that it means we need to decide from case to case, I would be fine with just closing this ticket without further action.

[epatpol]

Let's close it for now but still merge the PR? I like the addition of ... to the git commands that need further actions.

[akosyakov]

If a label is shown in a certain context (i.e. context menu of a widget), it can be shorted (omitting that obvious context information). E.g. Merge... instead of Git: Merge...

Maybe, we need an explicit concept as a command category:

• in the global places, we can always prefix ${category}: {label}, although I can imagine that Editor prefix can be skipped in the command palette if a current widget is an editor and Git prefix can be skipped for Git submenu
• for context menus, we can use one variant or another. I would find it nicer than taking a substring as now.
• we could introduce conventions based on which menus can decide how a label should be rendered for the given command, e.g. if the last menu segment or menu label matches a command category then just render a label otherwise use a prefixed label

[epatpol]

in the global places, we can always prefix ${category}: {label}, although I can imagine that Editor prefix can be skipped in the command palette if a current widget is an editor and Git prefix can be skipped for Git submenu

Agreed, and because the editor commands only appear when there is an editor opened, there's not much to change here.

we could introduce conventions based on which menus can decide how a label should be rendered for the given command, e.g. if the last menu segment or menu label matches a command category then just render a label otherwise use a prefixed label

So we define labels inside commands with the prefix, but when we're about to render them we check if that label is prefixed by the menu category. If yes, render the end of it otherwise use the whole label. Is that it? Or you would define another label in the interface? Sorry if I completely misunderstood here!