What should dotnet --version display? #3773

Open
neman opened this Issue Jul 4, 2016 · 19 comments

Projects

None yet

9 participants

@neman
neman commented Jul 4, 2016 edited

Steps to reproduce

I installed .NET Core SDK for Windows.
When I type dotnetin pwsh it showed

Microsoft .NET Core Shared Framework Host

Version : 1.0.1
Build : cee57bf6c981237d80aa1631cfe83cb9ba329f12
Usage: dotnet [common-options] [[options] path-to-application]

Common Options:
--help Display .NET Core Shared Framework Host help.
--version Display .NET Core Shared Framework Host version.

...

When I type `dotnet --version it shows

1.0.0-preview2-003121

Expected behavior

I don't know what is expected behaviour.

Actual behavior

I have 2 different versions showing.
One is 1.0.1 and the other one is 1.0.0-preview2-003121

Is this a bug? Microsoft .NET Core Shared Framework Host show different versions or first version is .NET Core version so the problem is only within label name?

Environment data

dotnet --info output:

.NET Command Line Tools (1.0.0-preview2-003121)

Product Information:
Version: 1.0.0-preview2-003121
Commit SHA-1 hash: 1e9d529

Runtime Environment:
OS Name: Windows
OS Version: 10.0.10240
OS Platform: Windows
RID: win10-x64

@neman neman changed the title from What is my dotnet real version? to What should dotnet --version display? Jul 4, 2016
@dasMulli
Contributor
dasMulli commented Jul 4, 2016
  1. It is by design.. there are multiple components to the cli: muxer, shared host, shared framework, SDK.
  2. I do think the wording cold be better as the dotnet --help command will call out to the SDK but the help text is "Display .NET Core Shared Framework Host help". If you don't have an SDK installed, you will get the same info for no arguments, --help, and --version.
@blackdwarf blackdwarf added this to the 1.0.0-rtm milestone Jul 21, 2016
@blackdwarf blackdwarf self-assigned this Jul 21, 2016
@vcsjones
Contributor

There have been a number of issues filed, confusion on Slack channels, and on twitter about the meaning of dotnet --version.

Proposal: dotnet --version should print all relevant information. Something like this:

CLI Tooling: 1.0.0-preview4-004130
Microsoft .NET Core Shared Framework Host: 1.1.0
MSBuild: 15.1.0.0

The only reason I could think of as why this would be a bad idea is if the output of --version was meant to be parsable / consumable by other tools.

@omajid
Member
omajid commented Nov 29, 2016

@vcsjones Agreed. The only suggestion I have for your proposal is that the most important version number should be displayed first. I think most users will care about the .NET Core version first and foremost, so, ideally, that should come first.

@am11
am11 commented Nov 29, 2016

+1 for @vcsjones's proposal with an addition of NuGet version. :)

meant to be parsable / consumable by other

Agree, parsers will need to split by linefeed then by colon to get proper key value pairs, but if the --version output format and order is frozen once and for all (future tools listed at the bottom), that would be A-okay IMO.

@vcsjones
Contributor
vcsjones commented Nov 29, 2016 edited

Agree, parsers will need to split by linefeed then by colon to get proper key value pairs, but if the --version output format and order is frozen once and for all (future tools listed at the bottom), that would be A-okay IMO.

My concern is if there is a tool already that reads the entire string, like Visual Studio RC, to figure out the version of the SDK installed. That would mean changing this would break VS, which is probably a no-go.

If there is no tooling that already depends on this behavior, then line feeds are an option. Alternatively, --version could take an argument to return a specific thing, like --version sdk or --version msbuild, etc and it would instead literally print that version number like it is today.

@blackdwarf
Contributor
blackdwarf commented Nov 29, 2016 edited

I would disagree with changing the --version for this. It was introduced precisely because it gives back only the CLI version; this is how most of the other CLI toolkits out there that have two different ways to report versions work. Changing this would break people.

We do have the --info and we are exploring how to make that better. This suggestion is good and could go into --info along other information that is relevant (for instance, the host information).

@omajid users can potentially have multiple .NET Core shared runtimes installed on a single machine, so which one would be the one to bubble up? For example, I currently have 1.0.0, 1.0.1 and 1.1.0 on my machine. I believe that we should do something else to allow listing of installed runtimes.

@vcsjones
Contributor

this is how most of the other CLI toolkits out there that have two different ways to report versions work.

Not to disagree with you, but really to answer my own curiosity, can you give an example?

We do have the --info and we are exploring how to make that better

That's great. I would also consider improving what is displayed when dotnet is run with no arguments at all. Most things that I use use that for the REPL, but I don't think that's coming down the pipe any time soon.

Here's a dump of all of my silly thoughts.

  1. --info should include the runtime version. Please, somehow, think of something better to call it than "Microsoft .NET Core Shared Framework Host".
  2. Please add --info into "Common Options" when dotnet is run with no arguments. I realize it's there under --help already, but I feel this is going to be a common question.
  3. It's weird that dotnet --version, dotnet --info are affected by the global.json's "sdk". Ideally --info would show all your SDKs installed, somehow. Even if I had preview4 installed, but run dotnet --info in a directory which has a global.json SDK for preview2, it returns the preview2 version. This is technically right behavior, but it still doesn't seem quite right. I'm not aware of any other platforms like dotnet that do muxing like this, so I can't think of a better way to do it.
@omajid
Member
omajid commented Nov 29, 2016

@omajid users can potentially have multiple .NET Core shared runtimes installed on a single machine, so which one would be the one to bubble up?

@blackdwarf If there's multiple possible versions and any of them will work, maybe list them all?

@dasMulli
Contributor
dasMulli commented Nov 29, 2016 edited

The wording is quite inconsistent at the moment.
dotnet tells me:

...
Microsoft .NET Core Shared Framework Host

  Version  : 1.1.0
...
Common Options:
  --help                           Display .NET Core Shared Framework Host help.
  --version                        Display .NET Core Shared Framework Host version.

So. i just saw "Shared Framework Host version 1.1.0" and "--version shows the shared framework host version".
But dotnet --version really tells me the CLI version (1.0.0-preview4-004079).

@dasMulli
Contributor

Also there is --version and --fx-version which look similar, but one is actually a verb ("show version"), the other one is an option. This could be made more distinct (--use-fx-version 1.0.3 for example. with --fx-version still being supported for compatibility).

@blackdwarf
Contributor
blackdwarf commented Nov 29, 2016 edited

@vcsjones hm, I was sure I saw this behavior in node that it has two distinct outputs. Just tried it and it seems my memory is not what it was, since it has just one. To be fair though, both node and python display just their version on --version. To your other very good points, here is a summary reply (hope that works):

That's great. I would also consider improving what is displayed when dotnet is run with no arguments at all.

Yes, we are working on fixing this as it is super confusing to have 3 distinct versions (host, tooling and fx) to have to contend with, 2 out of which have

--info should include the runtime version. Please, somehow, think of something better to call it than "Microsoft .NET Core Shared Framework Host".

The host and the runtime are distinct components. ๐Ÿ™‚ The runtime version is not displayed anywhere, which is what @omajid is asking for (see response below on that)

It's weird that dotnet --version, dotnet --info are affected by the global.json's "sdk". Ideally --info would show all your SDKs installed, somehow. Even if I had preview4 installed, but run dotnet --info in a directory which has a global.json SDK for preview2, it returns the preview2 version. This is technically right behavior, but it still doesn't seem quite right. I'm not aware of any other platforms like dotnet that do muxing like this, so I can't think of a better way to do it.

I think we should leave it like this because that is the fastest way to check on what version you are and as you quite nicely said, it is technically correct behavior. We could see if a feature can be made at some point in the future that would list out the SDKs installed, but I'm not too sure if this is the way forward. Need to think on this.

@omajid

@blackdwarf If there's multiple possible versions and any of them will work, maybe list them all?

I'm in favor of having this capability in the CLI, just not as part of the --info or --version. I was thinking of adding at some point a --runtimes switch, for example, that would list out all of the runtimes that are near your host. I guess I'm following the underlying need here which is to have an easy gesture to list out the runtimes that you have installed on the system, correct?

@omajid
Member
omajid commented Nov 29, 2016

@blackdwarf My primary concern is that I get the following question when I point someone to .NET Core 1.1: "Why is the version 1.0.0-preview2-1? Did I install it incorrectly?" (see also #4864). This happened with multiple people, some of them who are generally much more knowledgeable than me when it comes to .NET. It seems to me that it's not obvious to many people that host, runtime (and cli?) are separate things. As far as I can tell, they ask for the version of .NET Core 1.1 and are confused when it doesn't say "1.1". Not many go as far as dotnet --info (this isn't as standard/obvious a flag as --version).

A --runtimes flag is nice to have, but I am not sure if it will help address the questions I have seen.

If a comparison to other languages/tools helps:

$ python --version
Python 2.7.12
$ python3 --version
Python 3.5.2
$ java --version 
openjdk version "1.8.0_111"
OpenJDK Runtime Environment (build 1.8.0_111-b16)
OpenJDK 64-Bit Server VM (build 25.111-b16, mixed mode)
$ gcc --version -Q
gcc (GCC) 6.2.1 20160916 (Red Hat 6.2.1-2)
Copyright (C) 2016 Free Software Foundation, Inc.
This is free software; see the source for copying conditions.  There is NO
warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
$ lua -v
Lua 5.3.3  Copyright (C) 1994-2016 Lua.org, PUC-Rio

Most other languages/projects seem to show the language's (or the runtime's) main version with the --version flag. None of the languages I tested print out the version of the driver ("cli") program. Given the existing set of tools out there, it seems very confusing to users if the dotnet cli program prints a version unrelated to the version of the rest of .NET Core.

@vcsjones
Contributor

they ask for the version of .NET Core 1.1 and are confused when it doesn't say "1.1".

Yes. That's more or less the issue. The issue is too many version numbers and discoverability.

That's why I was advocating for a single option, like --info, that dumps everything. The Muxer, Runtime, MSBuild, CSC, etc.

The question boils down to what is "the" version of .NET you have installed. The latest runtime? The current version of the tooling? It's marketed as the version of the runtime, more or less. Whatever "1.1" is, it's surprisingly hard to find it in the output of the .NET CLI.

@blackdwarf
Contributor

There seems to be a couple of issues that are conflating here, so let me try to tease them apart:

  1. I cannot find out the runtime I'm using from the CLI - this is true as today there is nothing that reports on what runtimes you have installed. The challenge here is the I'm using part in the sentence above. That bit is governed by the project and you can have multiple versions of .NET Core happilly installed side-by-side on your machine. That is why I still think a separate gesture to find out which runtimes are there is a better experience than potentially overloading --info.
  2. There are multiple versions and that is confusing - this is a good feedback and we heard it and are working on a plan on how to make this situation better. That plan will also inform what does the --info look like.
  3. I need to find out the versions of all the components - this is a fair request that becomes even more prononunced with Preview 3 of the tools. Again, --info is the place where I would put this and I think something along the lines of what @vcsjones suggests would be good.
  4. When I type X I get version Y, but then I get version Z - this is a similar problem to no 2 in this list and I'm working on a plan on how to unify these help screens to have a better experience/message that will not leave people scratching their heads.

Thoughts?

@vcsjones
Contributor
vcsjones commented Nov 30, 2016 edited

@blackdwarf

Thoughts?

That is a very good summary. Thank you. Those are all correct, and I fully agree with them.

That said, I'm still not sure all of this should be buried in --info instead of --version. I've used no other tool that displays version info behind a CLI option other than "version" (whether it is --version, version, -version is an entirely different matter).

These issues come up to discoverability. People will more than likely try "--version" first since every CLI tool on the planet uses something like that. They will see that version works, and prints something out, so they must have found the right command. If I were relatively new to the .NET Core ecosystem and had no idea of "runtime", "SDK", and "CLI", I would assume that --version was the right thing.

The basic problem comes down to that --version doesn't display what people think they are using. There is no mention at all of "1.0.0-preview2-1-003177" anywhere on this page:

screen shot 2016-11-30 at 12 57 41 pm

Since the CLI is the entry point into the .NET ecosystem, I think "--version" should reflect what the user thinks they are using.

@gortok
gortok commented Nov 30, 2016 edited

I agree with @vcsjones on the discoverability part; and to a new user, the difference between "SDK Version", "CLI Version", and "Runtime Version" isn't at all clear; we love our bins to put things in, but there should be one command that shows all the information a user needs when filling out a bug report asking for the 'version', and that should be the --version command.

I still don't quite understand how the tooling version numbers map to SDKs which maps to CLIs which maps to Runtimes, and I like to think I'm not stupid; but trying to figure this out makes me feel stupid.

@motowilliams

The expectations seem clear

Eric@machine_name MINGW64 ~
$ git --version
git version 2.9.0.windows.1

Eric@machine_name MINGW64 ~
$ less --version
less 481 (PCRE regular expressions)
Copyright (C) 1984-2015  Mark Nudelman

less comes with NO WARRANTY, to the extent permitted by law.
For information about the terms of redistribution,
see the file named README in the less distribution.
Homepage: http://www.greenwoodsoftware.com/less

Eric@machine_name MINGW64 ~
$ grep --version
grep (GNU grep) 2.24
Copyright (C) 2016 Free Software Foundation, Inc.
License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>.
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.

Written by Mike Haertel and others, see <http://git.sv.gnu.org/cgit/grep.git/tree/AUTHORS>.

Eric@machine_name MINGW64 ~
$ sed --version
sed (GNU sed) 4.2.2
Copyright (C) 2012 Free Software Foundation, Inc.
License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>.
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.

Written by Jay Fenlason, Tom Lord, Ken Pizzini,
and Paolo Bonzini.
GNU sed home page: <http://www.gnu.org/software/sed/>.
General help using GNU software: <http://www.gnu.org/gethelp/>.
E-mail bug reports to: <bug-sed@gnu.org>.
Be sure to include the word ``sed'' somewhere in the ``Subject:'' field.

Eric@machine_name MINGW64 ~
$ awk --version
GNU Awk 4.1.3, API: 1.1 (GNU MPFR 3.1.4, GNU MP 6.1.0)
Copyright (C) 1989, 1991-2015 Free Software Foundation.

This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 3 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program. If not, see http://www.gnu.org/licenses/.
@blackdwarf blackdwarf modified the milestone: 2.0.0, 1.0.0-rtm Jan 20, 2017
@blackdwarf
Contributor

Unfortunately, we are locked down with strings for 1.0.0. We will take a look at this post v1 and solve it then.

@NickCraver

FWIW, I just tried to explain this to someone...and I couldn't. They could not understand how things relate and how to correlate their --version to the website. I agree this really needs to change. People don't develop in the .NET tooling, the .NET runtime, and the .NET SDKs. This is a migration painpoint because users have gone from:

I'm on .NET 4.6.2

to

I'm on:
CLI: ________
SDK: _________
Runtime: _________

Basically we've replaced the .NET ecosystem with a bunch of exposed bits the user usually shouldn't be caring about. While this was fine during the transition for the power users involved here, it is definitely not okay going forward. The least we can do would be to simplify the gap and make it easy for the user to access all the bits they're on when getting help. Imagine what a user has to do on a build server to figure this out today. It's not intuitive, and is a large step backwards which will hurt migrations to .NET Core. I really wish this would be reconsidered for 1.0.0.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment