Offer noun-first commands for existing verbs where noun isn't obvious

[richlander]

Here is a sample (the first bit help) of CLI commands:

SDK commands:
  add               Add a package or reference to a .NET project.
  build             Build a .NET project.
  build-server      Interact with servers started by a build.
  clean             Clean build outputs of a .NET project.
  help              Show command line help.
  list              List project references of a .NET project.

• build, build-server and clean are obvious (to me) in terms of what they operate on
• add and list are not obvious what they operate on.
• help is a different case.

Please take a look at the rest of CLI commands to see where we should add noun-first commands to improve clarity/usability and align with the more recent noun-first commands (like tool) that have been added.

[KathleenDollard]

The CLI Syntax guidelines suggest that project is the default and all of these should be valid (project being optional as image is for many docker commands. I'd love your thoughts on that doc which has the review of current CLI commands you're suggesting (great!)

As a nuance, we are not saying noun first. Two "nouns" are often in play. The first position "noun" is the "context". It may always be a noun and is often the thing acted on, but it has the purpose of narrowing scope.

dotnet project add ...
dotnet add ...
dotnet project build ...
dotnet build...
dotnet project clean ...
dotnet clean...
dotnet project list ...
dotnet list...

Among other things, being able to specify project allows you to have nice help on the things you can do to a project.

However, help and build-server are somewhat different.

help should always work. Whatever command and subcommands you've already typed can just be used to give you best available context sensitive help.

The build server is a separate thing. It is actually the noun on which we are working. Whatever started the build server, build-server ... affects it.

I think all but help and build-server should be in the backlog and I'd like to hear more thoughts on help and build-server

[richlander]

I think what I said was confusing. The list of commands I provided wasn't curated, just the first set from help, so I was giving my thoughts on them (and not biasing the set).

I was suggesting that build, build-server and clear are all fine. It is only add and list that have problems, IMO. I think the premise that the noun is always project unless otherwise specified is problematic. It's hard for me to think in those terms. Certainly, for build and run, there is no confusion. This isn't because people got the memo that project is implied. It's because build and run are both unique verbs with a strong alignment to project and they are also so commonly used that they demand to be top-level. No one wants to type dotnet project build.

The problem with add and list is that they are not unique verbs. You may want to list many things. For me, at least, it is hard to draw the mental association that there is an implied project in front of list. I have a mental block on add and always have to remember how package and package are different.

The Docker CLI solves this particular problem:

• docker image ls lists the set of images on your machine
• docker images is a convenience wrapper over docker image ls
• There are many other verbs under docker image but I think ls is the only verb that gets a top-level wrapper because of how often people want to use it.
• docker ps is a wrapper for docker container ls ... same model, with even more liberty since the name changes entirely (for obvious reasons)

[KathleenDollard]

@richlander

Many of the image verbs in docker get top-level wrapper. 'build', 'import'... Only history, ls and prune are not documented to work on both, the rest do. This is the aspect of the docker CLI that we are learning from. Special case, but in a different way.

Also, docker images is a special case. All the CLIs I looked had special cases for immensely sensible things. If there are things we agree we all think should "just work" I think we'd break the rules. I think that is in the guidelines.

It would also be a breaking change to drop dotnet add or dotnet list. Adding dotnet project add package and dotnet project list package and supporting both give a better help experience, docker like flexibility in which one you remember, and no breaking change.

It was interesting when I evaluated CLI's and talked to people about CLI's, they generally hated git for it's lack of consistency, liked docker, and did minimal sensible things with npm so didn't really know it (the overloading of the most important npm command install is interesting). My assessment from these conversations was that you know you are working with a particular thing in most CLI (not az), although it's not something at the top of your consciousness.

So, too many words, but if you are just suggesting we add dotnet project add and dotnet project list, then we agree. But I don't think we should change the order of things here. dotnet list only list packages or references for the current project and there is no where else that package appears as a top level verb, meaning that it makes help much messier. "What can I do with a project?" help should give you a complete list.

[richlander]

I'm not suggesting making any breaking changes.

You are right. More docker image commands are projects. Good point.

dotnet list is a perfect example because it breaks down immediately. dotnet list on its own doesn't do anything useful. That's unfortunate for a top-level verb where the noun is expected to be implicit.

C:\git\redir\src\tests>dotnet list
Required command was not provided.
Usage: dotnet list [options] <PROJECT> [command]

Arguments:
  <PROJECT>   The project file to operate on. If a file is not specified, the command will search the current directory for one.

Options:
  -h, --help   Show command line help.

Commands:
  reference   List all project-to-project references of the project.

C:\git\redir\src\tests>dotnet list reference
Project reference(s)
--------------------
..\redir\redir.csproj

I wish we had the following commands instead:

• dotnet project references
• dotnet project packages

Anyway, my goal here wasn't to bike-shed but to raise the point that I think we need to take a second pass on top-level verbs like add and list. For me, they are not delightful to use and they feel inconsistent with the additions in .NET Core 2.1.300.

[KathleenDollard]

Let's do it (review commands)!

I think an in-room meeting with a doc, or an extension to the CLI guidelines doc that folks could comment on is my suggestion.

I'd love to be in town for it, if we can wait a couple weeks.

[richlander]

Great.

I won't be available until 9/3. In the meantime, please ask other people for input. I'm just one voice.