-
Notifications
You must be signed in to change notification settings - Fork 6k
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
update global.json #4704
Conversation
docs/core/tools/global-json.md
Outdated
- 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). |
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
docs/core/tools/global-json.md
Outdated
dotnet new globaljson --sdk-version 2.1.300-preview1-008174 | ||
``` | ||
|
||
## Matching rules |
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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.)
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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.
docs/core/tools/global-json.md
Outdated
|
||
The following .NET Core SDK version numbers are the officially supported .NET Core SDK versions: | ||
|
||
- 2.1.300-rc1-008673 |
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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?
There was a problem hiding this comment.
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.
@johnbeisner can you ensure your concerns are addressed. |
@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! |
docs/core/tools/global-json.md
Outdated
.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. |
There was a problem hiding this comment.
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
docs/core/tools/global-json.md
Outdated
|
||
.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. |
There was a problem hiding this comment.
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.
docs/core/tools/global-json.md
Outdated
|
||
## 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: |
There was a problem hiding this comment.
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 |
There was a problem hiding this comment.
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?
There was a problem hiding this comment.
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?
There was a problem hiding this comment.
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
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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
docs/core/tools/global-json.md
Outdated
|
||
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: |
There was a problem hiding this comment.
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 :)
There was a problem hiding this comment.
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.
docs/core/tools/global-json.md
Outdated
|
||
The SDK version is currently composed of the following parts: | ||
|
||
`[major][minor][xyz]-[additional optional information]` |
There was a problem hiding this comment.
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
There was a problem hiding this comment.
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
There was a problem hiding this comment.
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"?
There was a problem hiding this comment.
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.
docs/core/tools/global-json.md
Outdated
|
||
## 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. |
There was a problem hiding this comment.
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.
docs/core/tools/global-json.md
Outdated
- 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. |
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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? 🤣
There was a problem hiding this comment.
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?
docs/core/tools/global-json.md
Outdated
`[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`. | ||
|
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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?
docs/core/tools/global-json.md
Outdated
> [!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. |
There was a problem hiding this comment.
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).
docs/core/tools/global-json.md
Outdated
|
||
## Matching rules | ||
|
||
Starting with .NET Core SDK 2.0, the following rules apply when determining which version of the SDK to use: |
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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?
There was a problem hiding this comment.
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...
docs/core/tools/global-json.md
Outdated
- 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. | ||
|
There was a problem hiding this comment.
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.
docs/core/tools/global-json.md
Outdated
|
||
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`). |
There was a problem hiding this comment.
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.
docs/core/tools/global-json.md
Outdated
|
||
The SDK version is currently composed of the following parts: | ||
|
||
`[major].[minor].[xyz][-optional preview name]` |
There was a problem hiding this comment.
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.
docs/core/tools/global-json.md
Outdated
|
||
`[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`. |
There was a problem hiding this comment.
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. | ||
|
There was a problem hiding this comment.
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.
There was a problem hiding this 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" |
There was a problem hiding this comment.
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"?
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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.
This can get added back later, once #4704 is approved.
This can get added back later, once #4704 is approved.
* 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.
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