Update release notes format #6100

richlander · 2021-03-29T23:23:19Z

There are a few things that I thought could be improved with release notes that consistently cause me friction in using them.

Here are the problems I wanted to solve:

Find a better home home for dependencies. Today, we have the following docs (all of which should be deleted/replaced):
Package manager instructions should also be replaced.
- Preparing your Linux system for .NET Core
- Install using a Package Manager (with every updated)
The .NET Releases table never takes me to the place I want. I was the last person to substantially update this table, so this is entirely my fault.

Solutions (in the PR):

Each release defines the set of package dependencies, generally, and for multiple distros. This will include enabling people to contributes dependencies for distros we don't actually support.
Instructions will be moved to the release directory and not per update. This will (A) enable us to improve and refine a single document over the course of the release, and (B) provide people with a consistent link target.
Updated the releases table to something that (at least) I like.
I also deleted release notes links to preview releases. They are unnecessary. I deleted just the links not the release notes themselves.

Still left to do (can happen in another PR):

Stop producing the [version-number]-install-instructions.md doc for updates.
Delete the other content I referenced.
Add package installation instructions (for .NET dependencies) for other (at least the supported) distros.
Validate that the installation instructions are good/final.
Define a relationship between these installation docs and docs.ms.com/dotnet.
Make similar changes to .NET 5 and .NET Core 3.1.
Update the 6.0/linux-install.md doc.
Add the remainder of support distros to 6.0/linux-packages.md. Perhaps folks can help me with the RHEL ecosystem distros.

release-notes/6.0/linux-packages.md

danmoseley · 2021-03-30T00:09:07Z

release-notes/6.0/linux-packages.md

+- [GNU C Library (glibc)](https://www.gnu.org/software/libc/libc.html)
+- [GNU C++ Library](https://gcc.gnu.org/onlinedocs/libstdc++/)
+- [GCC low-level runtime library](https://gcc.gnu.org/onlinedocs/gccint/Libgcc.html)
+- [ICU](http://site.icu-project.org/)


ICU is optional.

bash is (I think) not optional for dotnet.

It isn't optional by default, but yes, I'll document invariant mode.

Is Kerberos optional?

Is Kerberos optional?

no

MichaelSimons

I like the improvements your are proposing.

os-lifecycle-policy.md

release-notes/2.1/README.md

release-notes/6.0/README.md

release-notes/6.0/install-windows.md

MichaelSimons · 2021-03-30T18:35:38Z

release-notes/6.0/install.md

@@ -0,0 +1,102 @@
+# .NET 6 installation instructions
+
+Concise install instructions for Windows are provided in this document, and may be augmented in [release notes](README.md) for a given update. Complete [.NET installation instructions for Windows, macOS, and Linux](https://docs.microsoft.com/dotnet/core/install/) are provided for supported releases in [.NET documentation](https://docs.microsoft.com/dotnet).


Concise instructions are also included for mac and linux.

Should the binary installation instructions be included in each of the OS specific instructions? It feels valuable to include the full set of installation types in one doc per OS.

The binary archive instructions don't necessarily feel like the most concise especially to noobs that may be more uncomfortable with cmd line instructions.

Good call. Fixed.

MichaelSimons · 2021-03-30T18:43:11Z

release-notes/6.0/linux-packages.md

+
+If your app relies on `https` endpoints, you'll also need to install `ca-certificates`.
+
+## Alpine 3.13


The distros listed here don't seem to match the distros listed in the supported-os.md. This seems like a disconnect.

You are right. I'll be adding those. I wasn't going to block the first merge on that. I was also going to farm some of that out. It will be much faster for someone else to add the RHEL ecosystem information, for example.

I'm good with that.

Hey, @richlander I can help with writing up the dependencies for RHEL/Fedora. Is there an application/test case I can use to verify that my list of dependencies is minimal but sufficient?

MichaelSimons · 2021-03-30T18:44:52Z

release-notes/6.0/linux-packages.md

+    zlib1g \
+```
+
+## Arch Linux (rolling build)


Given this is not supported, I find it strange to see listed here at the same level as the other distros. If you feel strongly about including it, maybe it should be under a community supported heading.

I'd like to encourage the community to (A) to support itself in these docs, (B) collect signal on which distros people want us to support.

Yes. I was wording about a "community supported" heading. I'll do that.

MichaelSimons · 2021-03-30T18:48:39Z

release-notes/README.md

@@ -1,14 +1,21 @@
-# .NET Core Release Notes


The need for both the README.md and releases.md doesn't seem strong? Is there a way to eliminate one? I suppose that is difficult without potential breaking links?

I spent a bunch of time thinking about that, when I first added releases.md. I came down to this configuration being best.

#5819 (comment)

mthalman · 2021-03-30T19:08:13Z

os-lifecycle-policy.md

@@ -4,16 +4,18 @@

 Each supported operating system has a lifecycle defined by its sponsor organization (for example, Microsoft, Red Hat, Debian, or Apple). The .NET team applies each of those lifecycle schedules to inform adding and removing support for operating system versions.


I think we need to be crisp on what classifications we're adhering to from each of these platforms. For example, Debian has three support levels: EOL, EOL LTS, and EOL ELTS. Which of those do we classify as being not supported for .NET? That needs to be described for all platforms.

In addition, not all our assets follow this support policy. For Docker, there is a more restrictive support policy. Should that be linked to from here?

Yes, some definition would be good. The original 2nd paragraph (marked as removed in this or) included additional detail that supported ended when an OS version went out of mainstream or free support.

I added a link to the Docker policy.

I added a policy section.

mthalman · 2021-03-30T19:11:29Z

release-notes/5.0/5.0-supported-os.md

@@ -1,6 +1,6 @@
 # .NET 5 - Supported OS versions

-[Microsoft supports](https://github.com/dotnet/core/blob/main/microsoft-support.md) .NET 5 with multiple operating systems, in alignment with official operating system lifecycle and distribution.
+[.NET 5](README.md) is supported on multiple operating systems per their lifecycle.


Link to os-lifecycle-policy.md

mthalman · 2021-03-30T19:22:08Z

release-notes/6.0/install-linux.md

+1. Create a directory to use for the download location and change into that directory. For example `mkdir $HOME/dotnet_install && cd $HOME/dotnet_install`
+2. Run `curl -L https://aka.ms/install-dotnet-preview -o install-dotnet-preview.sh`
+3. Run the script with `sudo bash install-dotnet-preview.sh`


This can be simplified to a one-line install:

curl -L https://aka.ms/install-dotnet-preview | sudo bash

mthalman · 2021-03-30T19:24:32Z

release-notes/6.0/install-linux.md

+
+`sudo snap install dotnet-sdk --channel=6.0/beta --classic`
+
+When .NET Core is installed using the Snap package, the default .NET Core command is `dotnet-sdk.dotnet`, as opposed to just `dotnet`. The benefit of the namespaced command is that it will not conflict with a globally installed .NET Core version you may have. This command can be aliased to `dotnet` with:


Since this is .NET 6 we're talking about, remove references to ".NET Core".

release-notes/6.0/install.md

mthalman · 2021-03-30T19:33:45Z

release-notes/6.0/linux-packages.md

@@ -0,0 +1,99 @@
+# Linux package dependencies
+
+.NET 6 has several dependencies that must be satisfied to run .NET apps. The commands to install these libraries are listed for multiple distributions.


There's overloading of the word "distribution" in these changes that can be ambiguous in some cases. I would suggest using "Linux distribution" in cases like this.

mthalman · 2021-03-30T19:35:18Z

release-notes/6.0/linux-packages.md

+- [GNU C Library (glibc)](https://www.gnu.org/software/libc/libc.html)
+- [GNU C++ Library](https://gcc.gnu.org/onlinedocs/libstdc++/)
+- [GCC low-level runtime library](https://gcc.gnu.org/onlinedocs/gccint/Libgcc.html)
+- [ICU](http://site.icu-project.org/)


Is Kerberos optional?

no

mthalman · 2021-03-30T19:36:06Z

release-notes/6.0/linux-packages.md

+    zlib
+```
+
+## Debian 10 "bullseye"


Distro code names should be capitalized.

Looks like Ubuntu does that and Debian doesn't.

Hmm, looks like there's not much consistency: https://wiki.debian.org/DebianBullseye

Let's just do what you suggested and call it good.

leecow · 2021-03-30T19:58:42Z

os-lifecycle-policy.md

@@ -4,16 +4,18 @@

 Each supported operating system has a lifecycle defined by its sponsor organization (for example, Microsoft, Red Hat, Debian, or Apple). The .NET team applies each of those lifecycle schedules to inform adding and removing support for operating system versions.

-When an operating system version goes out of "mainstream" or "free" support, we stop testing that version and providing support for that version. This means that users will need to move forward to a supported operating system version to get support.


Per the comments above, some details around how we decide the OS support period are helpful.

Co-authored-by: Michael Simons <[email protected]> Co-authored-by: Matt Thalman <[email protected]>

rbhanda · 2021-03-30T21:13:37Z

microsoft-support.md

 * [.NET release policies](release-policies.md)
-* [.NET release lifecycle](releases.md)
 * [Operating system lifecycle](os-lifecycle-policy.md).


Should we rename to: ".NET Supported Operating System lifecycle" to follow the pattern of the bullets listed above. Plus this is more descriptive

mairaw

A few comments...

mairaw · 2021-03-30T21:08:34Z

os-lifecycle-policy.md

 * [.NET 5 supported OS versions](release-notes/5.0/5.0-supported-os.md)
 * [.NET Core 3.1 supported OS versions](release-notes/3.1/3.1-supported-os.md)
 * [.NET Core 2.1 supported OS versions](release-notes/2.1/2.1-supported-os.md)

-The following documents define (historical) operating system support for out-of-support .NET Core versions:
+## End-of-life .NET versions


We're using the term out of support versions on pages like https://dotnet.microsoft.com/download/dotnet

os-lifecycle-policy.md

release-notes/2.1/README.md

mairaw · 2021-03-30T21:17:00Z

microsoft-support.md

 * [.NET release policies](release-policies.md)
-* [.NET release lifecycle](releases.md)
 * [Operating system lifecycle](os-lifecycle-policy.md).

 Knowing key dates for a product lifecycle helps you make informed decisions about when to upgrade or make other changes to your software and computing environment.


should we be linking to https://dotnet.microsoft.com/platform/support/policy from this article?

Good call. Fixed.

release-notes/3.1/README.md

release-notes/6.0/install-macos.md

release-notes/6.0/install-windows.md

release-notes/6.0/install.md

mairaw · 2021-03-30T21:25:43Z

release-notes/6.0/install.md

+- .NET Runtime: includes the .NET runtime and libraries, enabling running console applications.
+- ASP.NET Core Runtime: includes the .NET and ASP.NET Core runtimes, enabling running console, and web applications.
+
+You are recommended to install the .NET SDK to develop and build applications, and to install one of the runtimes packages (like ASP.NET Core) to (exclusively) run applications.


You are recommended is a bit strange...

I'd say "We recommend that you install..."

release-policies.md

Co-authored-by: Maira Wenzel <[email protected]>

dleeapho · 2021-03-30T21:36:03Z

release-notes/6.0/install-linux.md

+- .NET Runtime: includes the .NET runtime and libraries, enabling running console applications.
+- ASP.NET Core Runtime: includes the .NET and ASP.NET Core runtimes, enabling running console, and web applications.
+
+You are recommended to install the .NET SDK to develop and build applications, and to install one of the runtimes packages (like ASP.NET Core) to exclusively run applications.


Wording? Perhaps: "We recommend you install..." Also same wording for the 3 other variants of the install*.md docs.

Co-authored-by: Maira Wenzel <[email protected]>

richlander added 12 commits March 28, 2021 09:13

Update release notes

99b02a7

Update release notes

63129a2

Update .NET 6 releae notes

4e38b44

Update table

f8cdc32

Update links

9885c5e

Update release table

2e1392d

Update 2.1

8bf975b

Update table

9afb40d

Update links

5493b9d

Add linux packages doc

d5f1f2b

Add link to packages doc

5af09c1

Update Arch instructions

a24f660

richlander requested review from leecow and rbhanda as code owners March 29, 2021 23:23

danmoseley reviewed Mar 30, 2021

View reviewed changes

release-notes/6.0/linux-packages.md Show resolved Hide resolved

danmoseley reviewed Mar 30, 2021

View reviewed changes

Add statement about globalization invariant mode

6babbec

MichaelSimons reviewed Mar 30, 2021

View reviewed changes

mthalman reviewed Mar 30, 2021

View reviewed changes

leecow reviewed Mar 30, 2021

View reviewed changes

richlander and others added 6 commits March 30, 2021 13:08

Apply suggestions from code review

76ebcbe

Co-authored-by: Michael Simons <[email protected]> Co-authored-by: Matt Thalman <[email protected]>

Update per feedback

df33ad1

Update link

5328e17

Add buster

acb3b6f

Update heading

25f821d

Cleanup wording

ae40b88

rbhanda requested changes Mar 30, 2021

View reviewed changes

Update per feedback

b6f6f5d

mairaw reviewed Mar 30, 2021

View reviewed changes

Update per feedback

0dbe894

Apply suggestions from code review

d073e69

Co-authored-by: Maira Wenzel <[email protected]>

dleeapho reviewed Mar 30, 2021

View reviewed changes

richlander and others added 3 commits March 30, 2021 14:38

Update perf feedback

40b761b

Update release-policies.md

1eaf410

Co-authored-by: Maira Wenzel <[email protected]>

Update per feedback

4972b39

richlander merged commit d05daa6 into dotnet:main Mar 31, 2021

richlander deleted the relnotes-refresh branch March 31, 2021 22:18

		@@ -0,0 +1,102 @@
		# .NET 6 installation instructions

		Concise install instructions for Windows are provided in this document, and may be augmented in [release notes](README.md) for a given update. Complete [.NET installation instructions for Windows, macOS, and Linux](https://docs.microsoft.com/dotnet/core/install/) are provided for supported releases in [.NET documentation](https://docs.microsoft.com/dotnet).


		If your app relies on `https` endpoints, you'll also need to install `ca-certificates`.

		## Alpine 3.13

		@@ -4,16 +4,18 @@

		Each supported operating system has a lifecycle defined by its sponsor organization (for example, Microsoft, Red Hat, Debian, or Apple). The .NET team applies each of those lifecycle schedules to inform adding and removing support for operating system versions.


		`sudo snap install dotnet-sdk --channel=6.0/beta --classic`

		When .NET Core is installed using the Snap package, the default .NET Core command is `dotnet-sdk.dotnet`, as opposed to just `dotnet`. The benefit of the namespaced command is that it will not conflict with a globally installed .NET Core version you may have. This command can be aliased to `dotnet` with:

		@@ -0,0 +1,99 @@
		# Linux package dependencies

		.NET 6 has several dependencies that must be satisfied to run .NET apps. The commands to install these libraries are listed for multiple distributions.

		@@ -4,16 +4,18 @@

		Each supported operating system has a lifecycle defined by its sponsor organization (for example, Microsoft, Red Hat, Debian, or Apple). The .NET team applies each of those lifecycle schedules to inform adding and removing support for operating system versions.

		When an operating system version goes out of "mainstream" or "free" support, we stop testing that version and providing support for that version. This means that users will need to move forward to a supported operating system version to get support.

Update release notes format #6100

Update release notes format #6100

Conversation

richlander commented Mar 29, 2021 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

MichaelSimons left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

mairaw left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

richlander commented Mar 29, 2021 •

edited

Loading