Install on Linux docs are verbose

[tmds]

For example: https://docs.microsoft.com/en-us/dotnet/core/install/linux-fedora, but applies to all Linux flavors.

What users are looking for is:

$ sudo dnf install dotnet-sdk-5.0

This should be at the top of the page (2nd or 3rd paragrah).

Instructions across Fedora versions are very similar. There is no reason to split them up and duplicate the same instructions for each version. The repo file should use a placeholder, like: baseurl=https://packages.microsoft.com/fedora/$releasever/prod/.
Fedora versions that are no longer supported should be removed (vs ❌ Please note that this version of Fedora is no longer supported.).

Do these sections apply to Fedora:

• Remove preview versions
• Troubleshoot the package manager

These sections feels out of place in the installing document:

• Dependencies
• Next steps

These sections are duplicated across many pages, and provide an alternate non Fedora-specific way of installing .NET. They could live in their own doc(s):

• Snap
• Scripted install
• Manual install

cc @omajid @adegeo @tdykstra @RheaAyase @dagood

[dagood]

/cc @dleeapho @NikolaMilosavljevic @MichaelSimons

Fedora versions that are no longer supported should be removed (vs ❌ Please note that this version of Fedora is no longer supported.).

In general we go out of our way to keep out of support versions of the Microsoft build artifacts available (e.g. on packages.microsoft.com) for users who are behind for whatever reason. We decided to keep old distros around in these docs in #17925. Is there a reason they should be removed for Fedora in particular?

It would make more sense to me if we relied solely on the Fedora distro package feeds to acquire .NET, but currently the page points at both that and packages.microsoft.com.

Do these sections apply to Fedora:

• Remove preview versions

Yes, the script that installs the 5.0-preview RPMs that interfere with installing 5.0.0 is able to run on Fedora, so someone may have used it and needs these instructions to get things fixed.

(Edit: I suppose this was only reported for Debian packages: #21509. Maybe it's worth checking and raising a new issue if it doesn't apply to RPMs.)

• Troubleshoot the package manager

As long as any option points to a feed on packages.microsoft.com, yes.

[adegeo]

Great feedback from both of you.

• One easy thing to do that might help the design is moving How to install other versions below the version sections.

• Some of these versions in the version table are small in text and it's possible people don't notice they're links. Perhaps we should adjust those to repeat the distro? ex: Fedora 33

[RheaAyase]

and it's possible people don't notice they're links

In light of KISS, that copypasta should be deleted :D
Every single version in it going forward will be a copypaste of the previous, the redundancy and the nightmare of maintaining it will get out of hand very quickly. All versions of Fedora should have the same instructions.

There is definitely no reason to list EOL copypasta's, and only if there is a difference between the two currently supported versions, then mention it.

[adegeo]

I'm not sure there is anything KISS-able with installing things on Linux 😄

Part of the design is to keep it easy for someone to update. You (as the maintainer of the content) doesn't need to learn 10 different format structures. Most of the content is written in include files and inject at the appropriate positions. We keep older versions so that customers can at least find out information about a specific version of .net or distro if their production environment doesn't allow them to upgrade.

Some linux users don't want placeholders, others want exact install instructions, if there are placeholders you can't copy\paste the instructions into the terminal and have it just work. There isn't an easy way to make it simple for someone to copy\paste the instructions except by reproducing them for each flavor.

[RheaAyase]

I'm not sure there is anything KISS-able with installing things on Linux

A what, why wouldn't there be, it's much simpler than on Windows :D
dnf install dotnet -> dnf remove dotnet = couldn't really be any easier. And if you're a clicker you can do the same very thing via GUI, type the "dotnet" word into the search box, then click install or remove.

And those are the exact install instructions, these should be the punch line on top of the page, not somewhere in the middle of it, buried. Just like the Windows docs have the huge DOWNLOAD button on top.

[tmds]

We decided to keep old distros around in these docs in #17925. Is there a reason they should be removed for Fedora in particular?

The rationale for keeping the EOL isn't mentioned in that issue. The rationale for not keeping them is they are no longer supported. That means system packages are no longer updated, which is just as bad as no longer updating .NET Core packages (because .NET Core packages use the system packages). So like EOL versions of .NET Core, I think they should be removed from the installing page.

It would make more sense to me if we relied solely on the Fedora distro package feeds to acquire .NET, but currently the page points at both that and packages.microsoft.com.

👍 for solely relying a single source.
I'd prefer this source to be the Fedora distro packages, even if that means .NET Core 2.1 is no longer available (it will be EOL in summer 2021). @omajid @RheaAyase do you share this opinion?

One easy thing to do that might help the design is moving How to install other versions below the version sections.

Yes, re-ordering things would help a lot. There should be a command section at the top that just works. Below there can be various sections that go into more detail and advanced use-cases.

Some of these versions in the version table are small in text and it's possible people don't notice they're links. Perhaps we should adjust those to repeat the distro?

We should work towards having instructions that work across the different versions.
Also when a distro gets upgraded to a newer version, the repo file should still be appropriate for that new version (by using the placeholders).

@adegeo what are your thoughts on the comments I have about these sections:

• Dependencies
• Next steps
• Snap
• Scripted install
• Manual install

[RheaAyase]

I'd prefer this source to be the Fedora distro packages, even if that means .NET Core 2.1 is no longer available (it will be EOL in summer 2021).

Indeed.

I'd really like to see top of the page line saying dnf install dotnet which will always be the latest sdk. Perhaps followed by dnf install dotnet-sdk-x.y and only after that a note that 2.1 isn't available in Fedora and other stuff.

[tmds]

I'd really like to see top of the page line saying dnf install dotnet which will always be the latest sdk.

In retrospect, I don't like that we have a dotnet package because .NET applications don't automatically work across major versions. And, when latest changes and you prune your packages, you may be removing a version you depend on.

[omajid]

+1 for solely relying a single source.

I'd prefer this source to be the Fedora distro packages, even if that means .NET Core 2.1 is no longer available (it will be EOL in summer 2021). @omajid @RheaAyase do you share this opinion?

I think these two statements are in conflict right now.

If I, as a Fedora user, want to use .NET on Fedora, the single source has to be Microsoft. I can't use .NET Core 3.1 from Fedora repos (packages don't exist). I can't use .NET 5 from Fedora repos (packages don't exist). The only way to offer a good user experience right now is to tell everyone to use Microsoft packages (and even that requires blocking Fedora packages).

In a future where 2.1 is EOL and 3.1 and 5.0 are both available in Fedora, I am going to agree that the docs should just tell users to install Fedora packages using dnf install dotnet-sdk-3.1 or dnf install dotnet-sdk-5.0.

In other words, I think we need to provide the bits and then fix the docs to reflect that. If we modify the docs right now to make Fedora the single source, we may provide users with misleading and incorrect information.

[tmds]

I'm confused. @omajid we're about to have .NET 5 packages in Fedora, right? And, aren't my 3.1 packages also in Fedora?

$ dnf list installed 'dotnet*3.1'
Installed Packages
dotnet-apphost-pack-3.1.x86_64                                                      3.1.10-1.fc32                                                     @updates
dotnet-hostfxr-3.1.x86_64                                                           3.1.10-1.fc32                                                     @updates
dotnet-runtime-3.1.x86_64                                                           3.1.10-1.fc32                                                     @updates
dotnet-sdk-3.1.x86_64                                                               3.1.110-1.fc32                                                    @updates
dotnet-targeting-pack-3.1.x86_64                                                    3.1.10-1.fc32                                                     @updates
dotnet-templates-3.1.x86_64                                                         3.1.110-1.fc32                                                    @updates

[omajid]

I'm confused. @omajid we're about to have .NET 5 packages in Fedora, right?

Yes, but "about to" might be as long as a few weeks (or months, unfortunately). It's not a matter of hours or even days.

I am just getting started on that now, and there's many things that I expect will trip me up.

[RheaAyase]

This issue won't be resolved by then, I think it's safe to make it depend on 5.0 ga in Fedora.

[omajid]

Yes, but "about to" might be as long as a few weeks (or months, unfortunately). It's not a matter of hours or even days.

There's a workaround: the dotnet-sig/dotnet copr repo now has both 2.1 and 5.0 (as well as EOL 3.0) packages, if we want to point users to that

[tmds]

There's a workaround: the dotnet-sig/dotnet copr repo now has both 2.1 and 5.0 (as well as EOL 3.0) packages, if we want to point users to that

Thanks Omair!

We see it as a workaround because we are unable to provide it directly from Fedora repositories. For end-users adding the copr repo is similar to adding the Microsoft repo.

I prefer using the copr repo over Microsoft repo. I'd be disappointed if we'd still use Microsoft packages as the default for Fedora after all the work that went into source-build.

For anyone wondering, the copr packages are production grade. They are similar to what gets shipped on RHEL.

might be as long as a few weeks (or months, unfortunately). It's not a matter of hours or even days.

We should see if we can shorten this delay for .NET 6.

[dagood]

I think we should split these pages: move Microsoft-built SDK instructions out, and put high emphasis on the distro-provided instructions. The default, distro-provided instructions can then be a lot less verbose without much question (IMO). The Microsoft build page can then keep the troubleshooting info, copy-pasta, related install methods (manual install), and old EOL instructions (or whichever of these things we're still interested in). The second page's info then wouldn't impact the experience of the 99% of people who should install source-built .NET from the distro feeds. The default page could direct people to the Microsoft feed page as appropriate, but without the noise of having the whole thing inline.

Add instructions to diagnose/fix errors caused by mixing Microsoft and source-built Linux packages #18347 is another reason I'm thinking of this. The Microsoft and distro feeds don't work nicely together, and we need more documentation about the incompatibilities. The need to add extra documentation only if the distro provides .NET packages makes splitting seem natural to me.

We should see if we can shorten this delay for .NET 6.

On the upstream side, we have dotnet/core#5437 tracking source-build improvements for .NET 6. Moving the source-build infra a lot earlier in the Microsoft build process is a major focus here. Instead of a pile of regressions to take care of each release, I hope we'll have continual builds to validate and refine.

[RheaAyase]

That's a good point @dagood many download pages in general list the recent versions and then have a separate page for "older versions" so splitting the page does make sense, to have the other / eol versions elsewhere, +1

[tmds]

Do I understand correctly. The proposal is to split the Fedora installation instructions in a Microsoft-build instruction page, and a distro-build instruction page?
Why don't we get rid of the Microsoft-build instructions all-together?
The distro specific page can have some troubleshooting for people that have added Microsoft's repos in the past.

[dleeapho]

I like the proposal of splitting the pages. The current interleaving of steps for MS-built vs distro-built is confusing. But I cannot wrap my head around the idea of splitting along those 'headings', to me it seems arbitrary. My guess is that customers think of MS-built vs distro-built as complementary, eg. Previews are going to be more frequent with MS-built so if the customer is interested in tracking previews they may opt for MS-built; whereas, for example, if the customer wants to deploy into production, they may opt for distro-built. I'm suggesting that splitting along the lines of use cases is better but I'm at a loss to come up with apt use cases.

[dagood]

Do I understand correctly. The proposal is to split the Fedora installation instructions in a Microsoft-build instruction page, and a distro-build instruction page?

Yep, with the distro-build instruction page being primary.

Why don't we get rid of the Microsoft-build instructions all-together?

For the not-in-support versions of .NET/the distro, it goes back to:

We keep older versions so that customers can at least find out information about a specific version of .net or distro if their production environment doesn't allow them to upgrade.

But if we only consider in-support versions and assume we move manual install + Snap install somewhere else, there's still the question of how often anyone would find it useful to use the Microsoft package feed over the distro's feed. There should ideally never be a benefit to use the Microsoft feed: all Microsoft-supported .NET major.minor releases are available from the distro, all updates are published on the same day as Microsoft's release (including previews), and there are no feature gaps between the Runtimes/SDKs available on both feeds. We're not at that ideal state, so I don't think we can hide the Microsoft feeds yet.

[tmds]

But if we only consider in-support versions

I think we should do that, and remove the eol distro versions from the doc.
#17925 doesn't provide the rationale for keeping eol distros in the docs.

all Microsoft-supported .NET major.minor releases are available from the distro, all updates are published on the same day as Microsoft's release (including previews), and there are no feature gaps between the Runtimes/SDKs available on both feeds. We're not at that ideal state, so I don't think we can hide the Microsoft feeds yet.

For Fedora, combining the Fedora default repos with the dotnet sig copr repo, we can provide users with all Microsoft-supported .NET versions.
I think that meets the bar, or what more is needed?

[dagood]

#17925 doesn't provide the rationale for keeping eol distros in the docs.

That's what this is about in this thread (yeah, I missed that the original discussion happened in an internal email thread, sorry):

We keep older versions so that customers can at least find out information about a specific version of .net or distro if their production environment doesn't allow them to upgrade.

[adegeo]

Even though I've not really commented much here, I've been taking this all in and playing around with some ideas. One thing I think we can easily do is pull out the snap/script installs into their own pages and link to them. This instantly reduces the scope of each distro page by quite a lot.

You can see from that image how much content will be removed from each distro page. If you have the appropriate permissions, you can check it out on the review site: https://review.docs.microsoft.com/en-us/dotnet/core/install/linux-snap?branch=pr-en-us-21946

PR #21946

Next I'll start looking at what to do about consolidating the distro pages

[adegeo]

Looking at reducing copy pasta how about something like this? Each page is tailored to the distro version. The out-of-support releases article is the copy-pasta version that lists each old version of the distro with those instructions archived for anyone that absolutely needs to know how to install for that specific release.

This does mean more work per release from the docs standpoint (creating a new article, redirecting old articles, adding to the archive, updating main article, etc)

Image preview of TOC

[tmds]

we can easily do is pull out the snap/script installs into their own pages and link to them. This instantly reduces the scope of each distro page by quite a lot.

@adegeo yes, removing Snap, Scripted install, Manual install will help a lot. Please go ahead and make that change.

Also the 'Next steps' feels out of place on the install page. It just sits there at the bottom. I think it may be removed completely.

Looking at reducing copy pasta how about something like this?

I'm not in favor. We should not have per distro version instructions. The repo files should work across versions using placeholders. Who is 'owner' of the repo files?

Some linux users don't want placeholders, others want exact install instructions, if there are placeholders you can't copy\paste the instructions into the terminal and have it just work.

This doesn't make sense. The instructions can be made to work copy-paste, and why would some users not want to user placeholders?

That's what this is about in this thread (yeah, I missed that the original discussion happened in an internal email thread, sorry):

I think we should exclude them for the reasons mentioned in #21878 (comment). It would be interesting to know why it was decided otherwise.

It doesn't make sense that some users would still be running a Fedora version that went EOL 2,5 years ago.

For Fedora, combining the Fedora default repos with the dotnet sig copr repo, we can provide users with all Microsoft-supported .NET versions.

At some point, we need to make the jump where we consider source-build at a good enough place to replace Microsoft build for Linux. I think/hope we have reached that point for Fedora.

[adegeo]

@tmds These pages were all originally created with the same design template that I came up with. It makes it easy for me to maintain and not worry about a distro-specific details. However, there are a few distros, such as Fedora, that seem to be a bit more managed than say Ubuntu.

These changes I was proposing were for all of the distro pages and not just Fedora specifically. Playing around with just the Fedora article I've done the following:

• Reverted the TOC changes (not pictured)
• Altered the version table
• Since .NET 5.0 isn't in the default package repository yet, this has its own section.
• Keep .NET Core 3.1 instructions since these use the default repository.
• Moved all other non-supported fedora versions into a single section
• Added next steps article for enabling tab completion (we have an org requirement to generally always have a next steps style section at the end of an article)

Image preview of article

[tmds]

@adegeo I like where this is going. I wouldn't mind making some time to propose something (after Christmas break) and get your thoughts about it.

From the stakeholders in this discussion (@omajid @RheaAyase @dleeapho @dagood) I'd like to know their opinion about two proposed changes:

• removing EOL versions of the distro
• removing microsoft package feeds, in favor of Fedora packages + dotnet-sig/dotnet copr repo.

If you think these changes make sense to you, add a 👍 to this message. If not, let us know why.

[dagood]

• removing EOL versions of the distro

@adegeo described the current reason to not do this in the thread:

We keep older versions so that customers can at least find out information about a specific version of .net or distro if their production environment doesn't allow them to upgrade.

I would characterize the approach taken with the docs so far as extremely conservative: if any customer might want access to the old .NET packages, don't delete information on how to get to them.

You mentioned:

The rationale for not keeping them is they are no longer supported. That means system packages are no longer updated, which is just as bad as no longer updating .NET Core packages (because .NET Core packages use the system packages).

This point seems orthogonal. The docs don't say using an EOL distro version is good. But I would agree that having a doc up with EOL versions could be used by someone as a signal that it's ok to use them, and it would make sense to remove them to prevent that.

Neither point seems to me to obviously win out. Rather it seems like it depends on which principles have more weight for whoever's making this decision.

---

So like EOL versions of .NET Core, I think they should be removed from the installing page.

The pages actually still describe how to get EOL versions: https://docs.microsoft.com/en-us/dotnet/core/install/linux-fedora#how-to-install-other-versions. The copy-paste instructions only show the current package's name, and you have to put together your own package name to get other versions, whether in-support 3.1, or 2.1, or EOL 3.0.

I do think it makes sense to be consistent, but since we make all .NET versions available at https://dotnet.microsoft.com/download/dotnet-core, that would point me towards keeping everything, to be consistent with the other ways we distribute Microsoft-built .NET binaries.

---

• removing microsoft package feeds, in favor of Fedora packages + dotnet-sig/dotnet copr repo.

What happens if a delay happens again for 6.0, any 5.0/3.1/2.1 servicing release, or any preview build? Can we really say this won't happen when even in this thread, the problems with 5.0 came up? I think that we can fix this in the future (and to be clear, IMO the problems are on the Microsoft build side), but to me, it seems far from proven.

Maybe there's room for leeway, e.g. maybe Linux users don't expect same-day packages, or are ok without RPM/Deb-installed previews in some cases. I don't have context here, so I default to a principle of absolute parity between source-build-available distros and and Microsoft-build-only distros.

This may be different for other distros: e.g. if we don't have reliable maintainership for some new distro, delays could happen quite often, even for security releases. Continuing to provide the Microsoft repo probably makes sense there. (Just wanted to point this out since the thread isn't only about Fedora--I think we do need the capability to document both approaches at the same time.)

Maybe we can be more responsive and swap out the instructions rapidly when we get in a situation like that. I don't like consciously planning to do emergency work, but maybe it's fine here.

[adegeo]

@dagood Check out my proposal for simplifying just the Fedora docs. This design might be good for those distros that offer .NET out of the box without adding some sort of additional feed:

Internal link only

[dagood]

Check out my proposal for simplifying just the Fedora docs.

I think it's reasonably organized, but it's still overwhelming the happy path for Fedora distro users. There's also some data that needs fixing to apply to only the right places (x64-only vs. x64+arm64, troubleshooting, preview package issues (probably?)), adding 2.1 back in, and detailing the danger/fixes for mixing Microsoft and distro repos. Once that's all resolved, the total amount of info is still going up, unless we do something more dramatic like split it.

[adegeo]

I think this content is in a good place and any specific change requests should be filed in new issues. One last thing I'll do though is add a link to the other version downloads in the include file.