New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

What should dotnet --version display? #3773

Closed
neman opened this Issue Jul 4, 2016 · 54 comments

Comments

Projects
None yet
@neman

neman commented Jul 4, 2016

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

This comment has been minimized.

Show comment
Hide comment
@dasMulli

dasMulli Jul 4, 2016

Contributor
  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.
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.
@vcsjones

This comment has been minimized.

Show comment
Hide comment
@vcsjones

vcsjones Nov 29, 2016

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.

Contributor

vcsjones commented Nov 29, 2016

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

This comment has been minimized.

Show comment
Hide comment
@omajid

omajid Nov 29, 2016

Member

@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.

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

This comment has been minimized.

Show comment
Hide comment
@am11

am11 Nov 29, 2016

Contributor

+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.

Contributor

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

This comment has been minimized.

Show comment
Hide comment
@vcsjones

vcsjones Nov 29, 2016

Contributor

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.

Contributor

vcsjones commented Nov 29, 2016

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

This comment has been minimized.

Show comment
Hide comment
@blackdwarf

blackdwarf Nov 29, 2016

Contributor

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.

Contributor

blackdwarf commented Nov 29, 2016

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

This comment has been minimized.

Show comment
Hide comment
@vcsjones

vcsjones Nov 29, 2016

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.
Contributor

vcsjones commented Nov 29, 2016

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

This comment has been minimized.

Show comment
Hide comment
@omajid

omajid Nov 29, 2016

Member

@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?

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

This comment has been minimized.

Show comment
Hide comment
@dasMulli

dasMulli Nov 29, 2016

Contributor

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).

Contributor

dasMulli commented Nov 29, 2016

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

This comment has been minimized.

Show comment
Hide comment
@dasMulli

dasMulli Nov 29, 2016

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).

Contributor

dasMulli commented Nov 29, 2016

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

This comment has been minimized.

Show comment
Hide comment
@blackdwarf

blackdwarf Nov 29, 2016

Contributor

@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?

Contributor

blackdwarf commented Nov 29, 2016

@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

This comment has been minimized.

Show comment
Hide comment
@omajid

omajid Nov 29, 2016

Member

@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.

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

This comment has been minimized.

Show comment
Hide comment
@vcsjones

vcsjones Nov 30, 2016

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.

Contributor

vcsjones commented Nov 30, 2016

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

This comment has been minimized.

Show comment
Hide comment
@blackdwarf

blackdwarf Nov 30, 2016

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?

Contributor

blackdwarf commented Nov 30, 2016

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

This comment has been minimized.

Show comment
Hide comment
@vcsjones

vcsjones Nov 30, 2016

Contributor

@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.

Contributor

vcsjones commented Nov 30, 2016

@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

This comment has been minimized.

Show comment
Hide comment
@gortok

gortok Nov 30, 2016

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.

gortok commented Nov 30, 2016

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

This comment has been minimized.

Show comment
Hide comment
@motowilliams

motowilliams Nov 30, 2016

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/.

motowilliams commented Nov 30, 2016

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 milestones: 2.0.0, 1.0.0-rtm Jan 20, 2017

@blackdwarf

This comment has been minimized.

Show comment
Hide comment
@blackdwarf

blackdwarf Jan 20, 2017

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.

Contributor

blackdwarf commented Jan 20, 2017

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

This comment has been minimized.

Show comment
Hide comment
@NickCraver

NickCraver Jan 20, 2017

Member

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.

Member

NickCraver commented Jan 20, 2017

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.

@karelz

This comment has been minimized.

Show comment
Hide comment
@karelz

karelz Mar 19, 2017

Member

@blackdwarf are you tracking it for next major release of the tooling? I think this is must have. I'll be happy to help shape the info. It is confusing even for me. I can help you dogfood it like I did the installation page ;-)

Member

karelz commented Mar 19, 2017

@blackdwarf are you tracking it for next major release of the tooling? I think this is must have. I'll be happy to help shape the info. It is confusing even for me. I can help you dogfood it like I did the installation page ;-)

@karelz

This comment has been minimized.

Show comment
Hide comment
@karelz

karelz Mar 21, 2017

Member

@livarcocc that sounds like a strong support based on customer need for a technical breaking change. What do you think?
cc @DamianEdwards

Member

karelz commented Mar 21, 2017

@livarcocc that sounds like a strong support based on customer need for a technical breaking change. What do you think?
cc @DamianEdwards

@livarcocc

This comment has been minimized.

Show comment
Hide comment
@livarcocc

livarcocc Mar 21, 2017

Member

Well, most of the issues called out in the twitter links above were about downloading a 1.1.1 file for the CLI installer and it carrying a CLI 1.0.1. The correct version IS 1.0.1 for the CLI and we have since fixed this 1.1.1 download link/button/etc.

--version lists the CLI version, it always has and I am reticent to breaking it, as this will potentially break multiple build scripts out there and CI is one of the main scenario for the CLI.

Member

livarcocc commented Mar 21, 2017

Well, most of the issues called out in the twitter links above were about downloading a 1.1.1 file for the CLI installer and it carrying a CLI 1.0.1. The correct version IS 1.0.1 for the CLI and we have since fixed this 1.1.1 download link/button/etc.

--version lists the CLI version, it always has and I am reticent to breaking it, as this will potentially break multiple build scripts out there and CI is one of the main scenario for the CLI.

@omajid

This comment has been minimized.

Show comment
Hide comment
@omajid

omajid Mar 21, 2017

Member

this will potentially break multiple build scripts out there and CI is one of the main scenario for the CLI

If project.json to csproj change was acceptable for 1.0 RC 2 to 1.0 SDK for CLI, surely a change in --version can be considered between 1.0 and 2.0?

Member

omajid commented Mar 21, 2017

this will potentially break multiple build scripts out there and CI is one of the main scenario for the CLI

If project.json to csproj change was acceptable for 1.0 RC 2 to 1.0 SDK for CLI, surely a change in --version can be considered between 1.0 and 2.0?

@PRIMETSS

This comment has been minimized.

Show comment
Hide comment
@PRIMETSS

PRIMETSS Mar 22, 2017

I think this that was suggested would be useful

SDKs:
1.0.0
1.0.1
Runtimes:
1.0.4
1.1.1

It will help people that are downloading sdk or runtimes, and expecting to see the version they downloaded.
But I think also there needs to be an indication of what is going to be built when you type dotnet.exe build, which will be influenced from external (another bit of magic) config info in the csproj
Other wise we are going to get people downloading cli v2_preview_xxx and they are going to imagine that the project they are building will produce a dotnet core version 2 of the app

How about a line that also says 'based on myproject.csproj build will output netcoreapp1.0'

eg

dotnet.exe --info

Installed:-

SDKs:
1.0.0
1.0.1
Runtimes:
1.0.4
1.1.1

dotnet build:
Based on myproject.csproj build will produce netcoreapp1.1

PRIMETSS commented Mar 22, 2017

I think this that was suggested would be useful

SDKs:
1.0.0
1.0.1
Runtimes:
1.0.4
1.1.1

It will help people that are downloading sdk or runtimes, and expecting to see the version they downloaded.
But I think also there needs to be an indication of what is going to be built when you type dotnet.exe build, which will be influenced from external (another bit of magic) config info in the csproj
Other wise we are going to get people downloading cli v2_preview_xxx and they are going to imagine that the project they are building will produce a dotnet core version 2 of the app

How about a line that also says 'based on myproject.csproj build will output netcoreapp1.0'

eg

dotnet.exe --info

Installed:-

SDKs:
1.0.0
1.0.1
Runtimes:
1.0.4
1.1.1

dotnet build:
Based on myproject.csproj build will produce netcoreapp1.1

@NickCraver

This comment has been minimized.

Show comment
Hide comment
@NickCraver

NickCraver Mar 22, 2017

Member

FWIW, I have no qualms with a --versions addition as described. It should be a list, not some JSON array style though (that's harder to read, and the whole thing isn't JSON so...). And it should be in --help, above --version, since it's the behavior more people seem to expect.

That combination doesn't break builds, but does prioritize the more intuitive and useful result for actual users.

Member

NickCraver commented Mar 22, 2017

FWIW, I have no qualms with a --versions addition as described. It should be a list, not some JSON array style though (that's harder to read, and the whole thing isn't JSON so...). And it should be in --help, above --version, since it's the behavior more people seem to expect.

That combination doesn't break builds, but does prioritize the more intuitive and useful result for actual users.

@omajid

This comment has been minimized.

Show comment
Hide comment
@omajid

omajid Mar 22, 2017

Member

I am afraid that if both --version and --versions are available, people will probably try the more common and obvious one --version and just go with that.

Member

omajid commented Mar 22, 2017

I am afraid that if both --version and --versions are available, people will probably try the more common and obvious one --version and just go with that.

@vcsjones

This comment has been minimized.

Show comment
Hide comment
@vcsjones

vcsjones Mar 22, 2017

Contributor

people will probably try the more common and obvious one --version and just go with that.

Agree. This is why I was hesitant to go with --info earlier.

Contributor

vcsjones commented Mar 22, 2017

people will probably try the more common and obvious one --version and just go with that.

Agree. This is why I was hesitant to go with --info earlier.

@tmds

This comment has been minimized.

Show comment
Hide comment
@tmds

tmds Mar 22, 2017

Member

+1 on fixing --version instead of patching/creating other options

It is preferable the output is easy to grep to figure out if a specific version is installed.

$ dotnet --version
Runtimes: 1.0.0, 1.0.3, 1.1.0
Sdks: 1.0.0-preview2-1-003177, 1.0.1
Member

tmds commented Mar 22, 2017

+1 on fixing --version instead of patching/creating other options

It is preferable the output is easy to grep to figure out if a specific version is installed.

$ dotnet --version
Runtimes: 1.0.0, 1.0.3, 1.1.0
Sdks: 1.0.0-preview2-1-003177, 1.0.1
@NickCraver

This comment has been minimized.

Show comment
Hide comment
@NickCraver

NickCraver Mar 23, 2017

Member

All valid points, so the only real disagreement I see is breaking --version. After seeing this discussion, confusion in the wild, and being frustrated with it personally, I'm in favor of --version showing everything (on a single line for multiples, as above).

We could request specific items version(s) via the 2nd parameter (--version <item>), for example: I recommend remapping --version to --version cli, to get that specific version for builds using it today. That's an easy migration to understand and reason about, without creating multiple commands.

I don't think we're unable to break people in 2.0, that's precisely when to do it for a net win. A lot of things are broken in build scripts due to parameters missing, SDK instal being inconsistent, etc. I think it's even hard to argue there's a very stable tooling chain out there at the moment (from an API and consistency standpoint). This is a good change, and we should make it.

Member

NickCraver commented Mar 23, 2017

All valid points, so the only real disagreement I see is breaking --version. After seeing this discussion, confusion in the wild, and being frustrated with it personally, I'm in favor of --version showing everything (on a single line for multiples, as above).

We could request specific items version(s) via the 2nd parameter (--version <item>), for example: I recommend remapping --version to --version cli, to get that specific version for builds using it today. That's an easy migration to understand and reason about, without creating multiple commands.

I don't think we're unable to break people in 2.0, that's precisely when to do it for a net win. A lot of things are broken in build scripts due to parameters missing, SDK instal being inconsistent, etc. I think it's even hard to argue there's a very stable tooling chain out there at the moment (from an API and consistency standpoint). This is a good change, and we should make it.

@TheRealPiotrP

This comment has been minimized.

Show comment
Hide comment
@TheRealPiotrP

TheRealPiotrP Mar 23, 2017

Collaborator

--version seems to be a fairly consistently implemented command line option:

Git

git --version
git version 2.10.1 (Apple Git-78)

cmake

cmake --version
cmake version 3.4.1

python

python --version
Python 2.7.11

go

go --version [fails. unsupported. had to read docs :-/]
go version
go version go1.8 darwin/amd64

dotnet

dotnet --version
2.0.0-preview1-005511

This was a random survey of popular developer tools on my machine. I have installed 3 versions of cmake and two versions of python. None of them even attempt to know anything about one another. All of them generate information about the tool that currently happens to be selected in my context, for whatever reason it was selected. The convention for a --version option is to print info about the version of the product that will be used in the current context. CLI does exactly the same.

dotnet, through its muxer, is capable of providing additional information and I think everyone agrees, per #6119, that it should. This is, as far as I can tell through my random survey, a new capability without prior art or conventions/expectations. When we enable this capability we should treat it as something new and provide a first-class experience. We shouldn't take an existing concept like --version and mutate it into something that fits our particular use case.

Collaborator

TheRealPiotrP commented Mar 23, 2017

--version seems to be a fairly consistently implemented command line option:

Git

git --version
git version 2.10.1 (Apple Git-78)

cmake

cmake --version
cmake version 3.4.1

python

python --version
Python 2.7.11

go

go --version [fails. unsupported. had to read docs :-/]
go version
go version go1.8 darwin/amd64

dotnet

dotnet --version
2.0.0-preview1-005511

This was a random survey of popular developer tools on my machine. I have installed 3 versions of cmake and two versions of python. None of them even attempt to know anything about one another. All of them generate information about the tool that currently happens to be selected in my context, for whatever reason it was selected. The convention for a --version option is to print info about the version of the product that will be used in the current context. CLI does exactly the same.

dotnet, through its muxer, is capable of providing additional information and I think everyone agrees, per #6119, that it should. This is, as far as I can tell through my random survey, a new capability without prior art or conventions/expectations. When we enable this capability we should treat it as something new and provide a first-class experience. We shouldn't take an existing concept like --version and mutate it into something that fits our particular use case.

@TheRealPiotrP

This comment has been minimized.

Show comment
Hide comment
@TheRealPiotrP

TheRealPiotrP Mar 23, 2017

Collaborator

I also think that this issue really belongs in the core-setup repo. You don't want to have to install developer tools just to learn about the versions of dotnet available on a random user's machine or a server deployment.

Collaborator

TheRealPiotrP commented Mar 23, 2017

I also think that this issue really belongs in the core-setup repo. You don't want to have to install developer tools just to learn about the versions of dotnet available on a random user's machine or a server deployment.

@karelz

This comment has been minimized.

Show comment
Hide comment
@karelz

karelz Mar 25, 2017

Member

@piotrpMSFT I think there is important difference between the tools you listed and dotnet.
dotnet does multi-targeting to .NET runtimes/versions. IMO the name itself suggests it is "the .NET" (as in the "go"), but in fact it is "dotnet_multiplexer" or "dotnet_environment". That's what makes it harder to understand IMO. Also the version number looks very similar (incl. suffix scheme) to the number of the targeted Runtime/Framework/SDK itself which adds on the confusion.
If it at least said what the version is for (".NET tooling, not the runtime") like other tools you listed do, I'd be happy.

Just my $0.02

Member

karelz commented Mar 25, 2017

@piotrpMSFT I think there is important difference between the tools you listed and dotnet.
dotnet does multi-targeting to .NET runtimes/versions. IMO the name itself suggests it is "the .NET" (as in the "go"), but in fact it is "dotnet_multiplexer" or "dotnet_environment". That's what makes it harder to understand IMO. Also the version number looks very similar (incl. suffix scheme) to the number of the targeted Runtime/Framework/SDK itself which adds on the confusion.
If it at least said what the version is for (".NET tooling, not the runtime") like other tools you listed do, I'd be happy.

Just my $0.02

@livarcocc

This comment has been minimized.

Show comment
Hide comment
@livarcocc

livarcocc Mar 25, 2017

Member

Overall, this issue exposes a number of bugs that are being conflated:

  • The .NET Core Version number story is confusing
  • A gesture to print all installed .NET Core Runtimes and SDKs would be useful. This is tracked by #6119.
  • The dot.net Web site showed an inconsistent SDK version number, adding to the Version Number story above. This has been fixed.
  • There is a great write up about UX improvements for the CLI in #6143 with suggestions that we have been able to converge towards.

The issues above have all either been fixed or are being tracked independently. I really appreciate everyone's help identifying all of these issues.

There is also a discussion here regarding the behavior of --version. As pointed out above, the CLI's behavior is very consistent with that of other similar products. Since --version is a commonly used option with a common behavior, and the CLI matches that behavior, making a change would simply make the CLI inconsistent. Furthermore, changing this behavior will break a behavior that was designed for programatic consumption. We are not going to take a breaking change that makes the dotnet CLI inconsistent with other CLIs.

Member

livarcocc commented Mar 25, 2017

Overall, this issue exposes a number of bugs that are being conflated:

  • The .NET Core Version number story is confusing
  • A gesture to print all installed .NET Core Runtimes and SDKs would be useful. This is tracked by #6119.
  • The dot.net Web site showed an inconsistent SDK version number, adding to the Version Number story above. This has been fixed.
  • There is a great write up about UX improvements for the CLI in #6143 with suggestions that we have been able to converge towards.

The issues above have all either been fixed or are being tracked independently. I really appreciate everyone's help identifying all of these issues.

There is also a discussion here regarding the behavior of --version. As pointed out above, the CLI's behavior is very consistent with that of other similar products. Since --version is a commonly used option with a common behavior, and the CLI matches that behavior, making a change would simply make the CLI inconsistent. Furthermore, changing this behavior will break a behavior that was designed for programatic consumption. We are not going to take a breaking change that makes the dotnet CLI inconsistent with other CLIs.

@ryanwalls

This comment has been minimized.

Show comment
Hide comment
@ryanwalls

ryanwalls Jul 6, 2017

The fact that I had to come here to read this thread to figure out that I am in fact using .net core 1.1.12 even though my dotnet --version command prints out 1.0.4 is an indicator that something is wrong. I'm not sure the argument that "CI is one of the main scenario for the CLI" is valid. Plenty of developers (especially unix/mac devs) will only want to use the CLI.

ryanwalls commented Jul 6, 2017

The fact that I had to come here to read this thread to figure out that I am in fact using .net core 1.1.12 even though my dotnet --version command prints out 1.0.4 is an indicator that something is wrong. I'm not sure the argument that "CI is one of the main scenario for the CLI" is valid. Plenty of developers (especially unix/mac devs) will only want to use the CLI.

@omajid

This comment has been minimized.

Show comment
Hide comment
@omajid

omajid Oct 27, 2017

Member

I also think that this issue really belongs in the core-setup repo. You don't want to have to install developer tools just to learn about the versions of dotnet available on a random user's machine or a server deployment.

Agreed. For an example of user confusion, see: https://stackoverflow.com/questions/46082280/what-is-the-best-way-of-installing-dotnet-core-on-a-raspberry-pi

Member

omajid commented Oct 27, 2017

I also think that this issue really belongs in the core-setup repo. You don't want to have to install developer tools just to learn about the versions of dotnet available on a random user's machine or a server deployment.

Agreed. For an example of user confusion, see: https://stackoverflow.com/questions/46082280/what-is-the-best-way-of-installing-dotnet-core-on-a-raspberry-pi

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