added note about sdk 2.1 #4385
added note about sdk 2.1 #4385
Conversation
docs/core/versions/index.md
Outdated
| @@ -19,9 +19,13 @@ This article aims at clarifying how the .NET Core SDK and runtime are versioned. | |||
|
|
|||
| There are lots of moving parts that version independently in .NET Core. However, starting with .NET Core 2.0, there is an easy to understand top-level version number that everybody understands to be *the* version of ".NET Core" as a whole. The rest of this document goes into the details of the versioning of all those parts. These details can be important if you're a package manager, for example. | |||
|
|
|||
| > [!IMPORTANT] | |||
| > The versioning details explained on this topic don't apply to the current version of the .NET Core SDK and runtime. | |||
| > The version scheme is changing on future releases and you can see the current proposal at the [dotnet/designs](https://github.com/dotnet/designs/pull/29) repository. | |||
There was a problem hiding this comment.
on future releases --> in future releases
Instead of "and you can see", it's better to have a new sentence ("You can see the current...")
docs/core/versions/index.md
Outdated
| @@ -31,7 +35,7 @@ The use of a single version number makes it easier for users to know what versio | |||
|
|
|||
| ### Installers | |||
|
|
|||
| Starting with .NET Core 2.0, downloads for our [daily builds](https://github.com/dotnet/core-setup#daily-builds) and [our releases](https://www.microsoft.com/net/download/core) adhere to a new naming scheme that is easier to understand. | |||
| With .NET Core 2.0, downloads for the [daily builds](https://github.com/dotnet/core-setup#daily-builds) and [releases](https://www.microsoft.com/net/download/core) adhere to a new naming scheme that is easier to understand. | |||
| The installer UI in those downloads were also modified to clearly present the names and versions of the components being installed. In particular, titles now show the same version number that is in the download's file name. | |||
docs/core/versions/index.md
Outdated
| @@ -114,7 +118,7 @@ A general Docker tag naming convention is to place the version number before the | |||
|
|
|||
| The SDK tags should be updated to represent the SDK version rather than Runtime. | |||
|
|
|||
| It's also possible that we need to fix the .NET Core Tools but reship an existing runtime. In that case, the SDK version is increased (for example, to 2.1.2) and then the Runtime catches up the next time it ships (for example, both the Runtime and SDK ship the following time as 2.1.3). | |||
| It's also possible that the .NET Core Tools need to be fixed but reship an existing runtime. In that case, the SDK version is increased (for example, to 2.1.2) and then the Runtime catches up the next time it ships (for example, both the Runtime and SDK ship the following time as 2.1.3). | |||
There was a problem hiding this comment.
changing the voice from active to passive makes the meaning of reship unclear here. Better might be, "It's also possible that the .NET Core Tools are fixed but reship with an existing runtime" or something similar.
comma before "and then"
docs/core/versions/index.md
Outdated
| @@ -124,26 +128,29 @@ It's also possible that we need to fix the .NET Core Tools but reship an existin | |||
| MAJOR.MINOR.PATCH[-PRERELEASE-BUILDNUMBER] | |||
| ``` | |||
|
|
|||
| The optional `PRERELEASE` and `BUILDNUMBER` parts will never be part of supported releases, and only exist on nightly builds, locally built from source targets, and unsupported preview releases. | |||
| The optional `PRERELEASE` and `BUILDNUMBER` parts are never part of supported releases, and only exist on nightly builds, locally built from source targets, and unsupported preview releases. | |||
There was a problem hiding this comment.
no comma before "and only exist"
locally built --> local builds
docs/core/versions/index.md
Outdated
| - Bug fixes are made. | ||
| - Support for a newer platform is added. | ||
| - A newer `PATCH` version of an existing dependency is adopted. | ||
| - Any other change that doesn't fit one of the previous cases. |
There was a problem hiding this comment.
"that" can be deleted here ("Any other change doesn't fit one of the previous cases.")
There was a problem hiding this comment.
is it wrong? otherwise it sounds better with it for me
There was a problem hiding this comment.
I'm fine with it either way, but since this is an expansion of "Patch is incremented when", it can be read as, "Patch is incremented when any other change that doesn't fit one of the previous cases." That interferes with the meaning; so "Path is incremented when any other change doesn't fit one of the previous cases." sounds better.
docs/core/versions/index.md
Outdated
| @@ -200,7 +207,7 @@ Versioning for .NET Core metapackages is based on the .NET Core version they are | |||
|
|
|||
| For instance, the metapackages in .NET Core 2.1.3 should all have 2.1 as their `MAJOR` and `MINOR` version numbers. | |||
|
|
|||
| The patch version for the metapackage is incremented every time any referenced package is updated. Patch versions don't include an updated framework version. As a result, the metapackages aren't strictly SemVer-compliant because their versioning scheme doesn't represent the degree of change in the underlying packages, but primarily the API level. | |||
| The patch version for the metapackage is incremented every time any referenced package is updated. Patch versions don't include an updated framework version. As a result, the metapackages aren't strictly SemVer-compliant because their versioning scheme doesn't represent the degree of change in the underlying packages, but primarily the API level. | |||
There was a problem hiding this comment.
primarily of the API level?
|
I've addressed your feedback @rpetrusha. Thanks! |
|
@Petermarcu @karelz since I'm touching this topic, the other day I saw on gitter someone asking about what line 182 means and I wasn't exactly sure how to explain that to him:
Is there a way we can write this using layman's terms? |
|
@steveharter can you please help while I am OOF? |
|
@mairaw here's the line you are asking about:
If we want to keep it short I think this is fine:
If we want to elaborate a bit more:
|
|
+1 on the first suggestion from @steveharter . |
|
Thank you @steveharter and @Petermarcu. That makes things a lot clearer. |
| > [!IMPORTANT] | ||
| > The versioning details explained on this topic don't apply to the current version of the .NET Core SDK and runtime. | ||
| > The version scheme is changing in future releases. You can see the current proposal at the [dotnet/designs](https://github.com/dotnet/designs/pull/29) repository. | ||
|
|
There was a problem hiding this comment.
It think we can explain it if we use a few more words. How about:
The .NET Core SDK and .NET Core runtime are released independently and therefore their version numbers are independent. The first attempt at resolving this challenge was to abandon aligning their numbers and simply version them separately using semantic versioning. This resulted in considerable confusion, so the approach has been changed to return to alignment between the SDK and runtime. Since the semantic versioning approach was short lived, it is largely ignored in this document, but you will find SDK version numbers in the 2.1.n range that shipped with 2.0.5 versions of the runtime. You can see the future SDK version numbering plan at the dotnet/designs repository.
@KathleenDollard see if this works for now until we don't have the new version in place
Related to #4352