Skip to content

update global.json #4704

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

Merged
merged 6 commits into from
Jul 9, 2018
Merged

update global.json #4704

merged 6 commits into from
Jul 9, 2018

Conversation

mairaw
Copy link
Contributor

@mairaw mairaw commented Mar 20, 2018

Fixes #2902
Fixes #5486
Fixes #5250

WIP since this is still missing the VS info. Please let me know if this looks good/accurate so far and how I can describe the VS info.

Internal review URL

- If *global.json* doesn't contain a version or a *global.json* file cannot be found, the latest installed SDK version is used (release or pre-release).
- If *global.json* does contain a version:
- If the specified version is found on the machine, that exact version is used.
- If the specified version cannot be found on the machine, the latest **patch** of the specified version is used (roll-forward along patch versions). For more information about versioning, see [Semantic versioning](../versions/index.md/#semantic-versioning).
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We aren't really using semantic versioning for the SDK starting in 2.1.300. We follow that intention with 2.1.xyy

@livarcocc or @dsplaisted should confirm but the intention is that we will roll forward in the last two digits, but the user might think the whole thing (300) is the patch.

Link to the current specification.

We might say we are rolling forward to the latest logical patch, which is the third position for versions earlier than 2.1.100 and the last two digits starting in 2.1.100.

I think there is a little goofiness in the roll forward of the SDK as we made the transition.

Copy link
Contributor Author

@mairaw mairaw Mar 22, 2018

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Good to know @KathleenDollard. I'll wait to hear from @livarcocc and @dsplaisted on the correct patch. I was assuming it was on the last position, not just the last two digits for newer SDKs.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@mairaw See here:

The SDK version rolls up only upon 'minor-patch' versions where the 'minor-patch' version is defined as the last two digits of the 'patch' version.

@mairaw mairaw added the WIP label Apr 5, 2018
@mairaw mairaw closed this Apr 5, 2018
@mairaw mairaw reopened this Apr 5, 2018
@nguerrera
Copy link

@johnbeisner

dotnet new globaljson --sdk-version 2.1.300-preview1-008174
```

## Matching rules
Copy link
Contributor

@johnbeisner johnbeisner Apr 16, 2018

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@mairaw
The description is nearly correct; any use of the term: "roll-forward" should not be used.

Matching rules

With .NET Core SDK 1.x, if you specified a version and no exact match was found, the latest installed SDK version was used. Latest SDK version can be either release or pre-release - the highest version number wins.

Starting with .NET Core SDK 2.0, the following rules apply when determining which version of the SDK to use:

  • If no global.json file is found, or the global.json doesn't contain a specified SDK version, the latest installed SDK version is used. Latest SDK version can be either release or pre-release - the highest version number wins.
  • If global.json does contain a specified SDK version:
    • If the specified SDK version is found on the machine, that exact version is used.
    • If the specified SDK version cannot be found on the machine, the latest installed SDK patch-version of the specified SDK version is used. Latest installed SDK patch-version can be either release or pre-release - the highest version number wins.
    • If the specified SDK version and an appropriate SDK patch-version cannot be found, an error is thrown.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Let's remove the sentence with semantic versioning since we are not using it.

Also, the language around the global.json file sort of makes it sound like it should be there. Let's change this

If global.json doesn't contain a version or a global.json file cannot be found

to

If no global.json file is found, or the global.json doesn't contain a version

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@mairaw
This should be ready. I've edited the "Matching rules" comment above - it should just cut 'n paste.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thank you @johnbeisner. I'll look at the feedback today and get this PR updated.

There was also a missing piece of this PR that is related to @nguerrera comment here: #2902 (comment)

It wasn't super clear to me how the VS/MSBuild case works and what happens when with the multiple possible combinations (VS versions earlier than 15.3 and later, SDK 1.1, SDK 2.0, etc.)

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I changed the wording a bit and tried to add some explanation of what the version number looks like and what constitutes a patch version.

Copy link
Contributor

@martingbrown martingbrown May 29, 2018

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

As someone new to .Net core it isn't clear to me what a patch version is? Is that the third number of the set. I.e in V2.1.200 the patch would be 200? If I specify 2.1 would I get 2.1.200 or 2.1.300-rc1? Maybe some examples would help.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm adding that info @martingbrown. For 2.1.300+, it's the last 2 digits of the last set.


The following .NET Core SDK version numbers are the officially supported .NET Core SDK versions:

- 2.1.300-rc1-008673
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is already out of date, missing 2.1.300 RTM (and others). This is going to be a pain to get updated.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We decided not to add this list like this @MisinformedDNA. I need to wrap this PR but other higher priority items took me away from this.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@mairaw I don't understand your comment. What's the value of this list here?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@KathleenDollard a customer was asking at #5250 but I didn't like it having it here so I will be removing when I finally have a chance to finish this PR. Instead, I'll add instructions about what to do when you get the preview message.

@KathleenDollard
Copy link
Contributor

@johnbeisner can you ensure your concerns are addressed.

@mairaw
Copy link
Contributor Author

mairaw commented Jun 27, 2018

@KathleenDollard @nguerrera @johnbeisner this is ready for a new review. I've left issue #5486 out of this update so I can understand that scenario better. But let me know if you feel that should come as part of this update as well. Please let me know if the topic looks good or if there's any other concerns I should address. Thanks!

@mairaw mairaw changed the title [WIP] update global.json update global.json Jun 27, 2018
@mairaw mairaw removed the WIP label Jun 27, 2018
.NET Core CLI tools look for this file in the current working directory (which isn't necessarily the same as the project directory) or one of its parent directories.
The *global.json* file allows selection of the .NET Core SDK version being used through the `sdk` property.

.NET Core SDK looks for this file in the current working directory (which isn't necessarily the same as the project directory) or one of its parent directories.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

for this file in -> for a global.json file in


.NET Core CLI tools look for this file in the current working directory (which isn't necessarily the same as the project directory) or one of its parent directories.
The *global.json* file allows selection of the .NET Core SDK version being used through the `sdk` property.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"The global.json file allows selection of which .NET Core SDK version will be used when you run .NET Core CLI commands.

I'd like to drop the "through the sdk property" part because it's actually the version property, sort of, is pedantic, not sure.


## global.json and the .NET Core CLI

Starting with .NET Core SDK 2.1, to verify which SDK versions you've installed to specify in the *global.json* file, you can run the following command:
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It is helpful to know which versions are available. You can find the full list of available SDKs. Starting with .NET Core SDK 2.1 you can run the following command to determine which SDK versions are installed:

dotnet new globaljson --sdk-version 2.1.300
```

## Matching rules
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should matching rules. be in the main global.json topic rather than reference?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

what is the main global.json topic? Would you like to split this in two? Customers complain this topic has too little information so maybe I could just tweak the title to be more generic like global.json overview and add a subsection called global.json reference?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think this rule might be better in the global.json overview.

If that leaves this topic too thin, you could fold it all into one

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

As discussed offline, this is the only topic, so keeping that here but reworking title and sections.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think this topic is covered here


With .NET Core SDK 1.x, if you specified a version and no exact match was found, the latest installed SDK version was used. Latest SDK version can be either release or pre-release - the highest version number wins.

Starting with .NET Core SDK 2.0, the following rules apply when determining which version of the SDK to use:
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@johnbeisner please confirm

This is .NET Core 2.1. It is actually NOT .NET Core SDK 2.1.n because it is packaged in the app host which is distributed with the .NET Core Runtime. So it is actually, "if you have ever installed a version of the .NET Core Runtime 2.1.0 or above, whether or not you uninstalled it to use a lower version" Yuk. ".NET Core 2.1" I think covers it. If they installed .NET Core SDK 2.1, or .NET Core Runtime 2.1, they've got it because .NET Core SDK 2.1 carries .NET Core Runtime 2.1

If you want to include this point, I can write something up. Because the potentially confusing thing, is that global.json does not affect the selection of global.json :)

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@johnbeisner can you please confirm? I'm trying to merge this PR ASAP.


The SDK version is currently composed of the following parts:

`[major][minor][xyz]-[additional optional information]`
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

unless this is following a standard, can we

additional optional information -> preview name

@johnbeisner can confirm, but I believe there is no other use for that position

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Not standard, it came from my head as I was trying to be generic. Not sure if the topic is still accurate but there were also other options for this position such as servicing. See https://docs.microsoft.com/en-us/dotnet/core/versions/#servicing-versions

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I see your point, but those daily builds are effectively previews of servicing releases. But it is a bit confusing

"preview or daily build name"?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think that preview is probably the most common case. So I'll change to preview but I'll keep optional so folks know it's not always there.


## Matching rules

With .NET Core SDK 1.x, if you specified a version and no exact match was found, the latest installed SDK version was used. Latest SDK version can be either release or pre-release - the highest version number wins.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can we put these in reverse chronological? I've put a comment about the 2.0 behavior that is hard to explain before they have read the 2.1 behavior.

- If no *global.json* file is found or *global.json* doesn't specify an SDK version, the latest installed SDK version is used. Latest SDK version can be either release or pre-release - the highest version number wins.
- If *global.json* does specify an SDK version:
- If the specified SDK version is found on the machine, that exact version is used.
- If the specified SDK version can't be found on the machine, the latest installed SDK **patch-version** of the specified SDK version is used. Latest installed SDK **patch-version** can be either release or pre-release - the highest version number wins.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If the specified SDK version can't be found on the machine, the latest installed SDK patch-version that is greater than the specified version of the specified SDK version is used. Latest installed SDK patch-version can be either release or pre-release - the highest version number wins.

That first sentence is now hard to parse. Perhaps split. "greater than specified" is super important.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm trying to think of a better way to explain this. I think saying "the latest installed SDK patch-version that is greater than the specified version of the specified SDK version is used." is not accurate.
For example, if I specified 2.1.300 and I have 2.1.401 on my machine, I have an installed SDK patch-version that is greater than the specified one, but that one is not picked because it's not a patch version of the version specified. Makes sense? 🤣

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ok, I think this simplifies things: "If the specified SDK version can't be found on the machine, the latest installed SDK patch-version of that version is used." Does that look ok to you?

`[major][minor][xyz]-[additional optional information]`

The **patch-version** is defined by the third position (`z`) in the last portion of the number (`xyz`) for SDK versions earlier than 2.1.100 and the last two digits (`yz`) starting with 2.1.100. For example, if you specify `2.1.300` as the SDK version, it can try to find up to `2.1.399` but `2.1.400` isn't considered a patch version for `2.1.300`.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Add:

.NET Core 2.0 contained slightly different behavior. If the specified version was not present the highest patch number was selected whether it was higher or lower than the one requested. Also, .NET Core SDK versions 2.1.100-2.1.201 were feature versions, but treated as patch versions for the purpose of global.json SDK selection. Both of these unusual behaviors have been fixed for later versions.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

.NET Core SDK 2.0 @KathleenDollard? Also, if the rules I stated earlier don't apply to .NET Core SDK 2.0, should I start the section by saying Starting with .NET Core SDK 2.1 instead?

> [!WARNING]
> You are working with a preview version of the .NET Core SDK. You can define the SDK version via a global.json file in the current project. More at https://go.microsoft.com/fwlink/?linkid=869452

This warning indicates that by default your project is being compiled using a preview version of the .NET Core SDK, as explained in the [Matching rules](#matching-rules) section. If that's not the desired behavior, add a *global.json* file to your project hierarchy structure to specify the SDK version you'd like to use.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This warning indicates that your project is being compiled using a preview version of the .NET Core SDK, as explained in the Matching rules section. .NET Core SDK versions have a history and commitment of very high quality, but if you don't want to use a preview, add a global.json file to your project hierarchy structure to specify the SDK version you'd like to use, and use dotnet --list-sdks to ensure that version is installed on your machine. You'll need to remove this global.json file when the new version releases and you'd like to use it.

(not having what they want installed might be the most common reason for getting this).
(we don't think this is a good reason to use global.json, but respect that our customers may choose to anyway, so I want to include our opinion here).


## Matching rules

Starting with .NET Core SDK 2.0, the following rules apply when determining which version of the SDK to use:
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should be .NET Core 2.0 (remove "SDK"). I hate to be pedantic, but this logic does not update with the SDK, but the apphost, which is released with the runtime.

Copy link
Contributor Author

@mairaw mairaw Jul 1, 2018

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sure I can. So let me confirm. If I have 1.1 SDK and then install 2.1 runtime only on my machine, when trying to resolve the SDK specified on global.json, it will use this logic and not the 1.1 logic. I might have to add a note about this then because it’s counterintuitive.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Rats. You brought up 1.1 SDK, which I am woefully unfamiliar with

@dsplaisted can you clarify this?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The version selection logic is part of the "Host" which is part of the .NET Core Runtime, but the latest version of the host is used when you have multiple Runtimes installed side-by-side.

So I think this can be worded as:

Starting with .NET Core 2.0, the following rules apply...

- If the specified SDK version is found on the machine, that exact version is used.
- If the specified SDK version can't be found on the machine, the latest installed SDK **patch-version** of that version is used. Latest installed SDK **patch-version** can be either release or pre-release - the highest version number wins.
- If the specified SDK version and an appropriate SDK **patch-version** can't be found, an error is thrown.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Add:

Starting in .NET Core 2.1, the patch versions lower than the patch specified are ignored in SDK selection.


The **patch-version** is defined by the last two digits (`yz`) in the last portion of the number (`xyz`) for SDK versions 2.1.100 and greater. For example, if you specify `2.1.300` as the SDK version, it can try to find up to `2.1.399` but `2.1.400` isn't considered a patch version for `2.1.300`.

.NET Core SDK 2.0 presented a slightly different behavior. If the specified version wasn't present, the highest patch version was selected, whether it was higher or lower than the one requested. Also, .NET Core SDK 2.0 versions 2.1.100 through 2.1.201 were feature versions, but treated as patch versions for the *global.json* SDK selection. Both of these unusual behaviors have been fixed for later versions. Also, for SDK versions earlier than 2.1.100, the **patch-version** was defined by the third position (`z`) in the last portion of the number (`xyz`).
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think this is my text, sorry, but it comes out complex. The text above is actually the 2.0 behavior and we can clarify just by adding a simple sentence on 2.1. People expect we stated the 2.1 behavior (they don't expect lower patches tone used.

So, with that change, let's drop this paragraph and add this:

.NET Core SDK 2.1.100 through 2.1.201 were released during the transition between version number schemes and do not correctly handle the xyz notation. We highly recommend if you specify these versions in global.json that you ensure the specified versions is on target machines.


The SDK version is currently composed of the following parts:

`[major].[minor].[xyz][-optional preview name]`
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It may be pedantic, but this isn't correct, in the sense I think people will expect. "minor" is not an SDK minor release and there's some indication in this that we use semantic versioning, which we do not. I suggest the following

[.NET Core major].[.NET Core minor].[xyz][-optional preview name]

The feature release of the .NET Core SDK is represented by the first digit (x) in the last portion of the number (xyz) for SDK versions 2.1.100 and greater. In general the .NET Core SDK has a faster release cycle than .NET Core.


`[major].[minor].[xyz][-optional preview name]`

The **patch-version** is defined by the last two digits (`yz`) in the last portion of the number (`xyz`) for SDK versions 2.1.100 and greater. For example, if you specify `2.1.300` as the SDK version, it can try to find up to `2.1.399` but `2.1.400` isn't considered a patch version for `2.1.300`.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

maybe

it can try -> SDK selection finds

Type: Object

Specifies information about the SDK.
Specifies information about the .NET Core SDK to select.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm seeing enough confusion that I would like to add the following, perhaps as a note:

Selecting the .NET Core SDK is independent from specifying the .NET Core Runtime your project targets. You specify the runtime [[ a few words and links for how you select target runtime ]]. The .NET Core SDK version indicates which versions of tools are used. In general you want to use the latest tools, and thus no global.json is needed.

@JRAlexander JRAlexander self-requested a review July 3, 2018 15:12
Copy link
Contributor

@JRAlexander JRAlexander left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM, except for a nit.

ms.author: mairaw
ms.date: 04/05/2017
ms.date: 07/02/2018
ms.custom: "updateeachrelease"
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should this also have "mvc" with a topic type of "conceptual"?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm not sure how you all do topics, but...

This is relevant for all .NET Core apps, there is nothing about MVC that makes it more or less relevant, so I would suggest not including it, or including all application types that work in .NET Core.

Copy link
Member

@BillWagner BillWagner Jul 3, 2018

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@KathleenDollard The "MVC" moniker here is an internal APEX term that refers to a content process. We have asked for a change because of confusion with the "ASP.NET MVC" product. The two are unrelated.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I thought that conceptual wasn't really a mvc topic type @JRAlexander.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

As far as I know, it is.

BillWagner referenced this pull request in BillWagner/docs Jul 3, 2018
This can get added back later, once #4704 is approved.
BillWagner referenced this pull request in BillWagner/docs Jul 4, 2018
This can get added back later, once #4704 is approved.
BillWagner added a commit that referenced this pull request Jul 4, 2018
* initial commit

Original design doc.
Updated TOC
Add paragraph in overview topic

* first draft complete

* proofread and grammar check

* respond to feedback

* fix merge

* fix a bad merge

* address detailed comments.

* one more round of detailed changes.

* rework focus

Reworked the focus based on feedback. This should be simpler, more scenario focused, and more clear for users.

* updated per product team feedback.

* fix link

* binding -> version

Per Product team feedback.

* update per feedback.

This can get added back later, once #4704 is approved.
@mairaw mairaw merged commit 8965131 into dotnet:master Jul 9, 2018
@mairaw mairaw deleted the globaljson branch July 9, 2018 17:09
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

9 participants