Update OS onboarding docs #115501
Update OS onboarding docs #115501
Conversation
github-actions
bot
added
the
needs-area-label
There was a problem hiding this comment.
Pull Request Overview
This PR updates the OS onboarding documentation to better clarify the differences between the main and release branches and to introduce a new OS Support Matrix document that outlines our testing coverage intent.
- Adds a new OS Support Matrix document to detail coverage levels for various operating systems.
- Updates the OS Onboarding guide to clarify testing approaches, OS lifecycle, and branch-specific strategies.
Reviewed Changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 1 comment.
| File | Description |
|---|---|
| docs/project/os-support.md | New document detailing OS support tiers and coverage intent. |
| docs/project/os-onboarding.md | Revised content clarifying testing, OS lifecycle, and branch update strategies. |
Co-authored-by: Copilot <[email protected]>
|
This is a first draft for the new doc. It needs some help. I believe the Linux part is right and then I'm not sure about other OSes and most are missing. |
| @@ -14,8 +14,9 @@ Continuing with the idea of pragmatism, if you only read this far, you've got th | |||
|
|
|||
| References: | |||
There was a problem hiding this comment.
It feels like the above section is leading with the "why" rather than the "what" -- that is, it is explaining our reasoning before mentioning the strategy. Should we invert that for people who are only interested in the "what"?
|
|
||
| The following tiers apply for Linux. | ||
|
|
||
| - Tier 1: Azure Linux, Debian, Ubuntu (in inner and outer loop) |
There was a problem hiding this comment.
I'd invert this language. That is, define what each tier means, then classify each OS as being in a particular tier.
|
|
||
| We rely on multiple levels of testing to provide good coverage at reasonable cost. Our testing uses OSes both as a vehicle to test .NET itself and to validate discover distro-specific breakage. This is why we test multiple OSes for each run type. | ||
|
|
||
| - Inner loop -- Baseline set of tests that validate correct functional behavior, for PRs and branch builds. |
There was a problem hiding this comment.
Maybe worth calling out that inner-loop for main means lots and lots of test coverage. For release branches it's just servicing fixes.
FWIW, it may be simpler to remove this distinction bewteen inner-loop only/outer-loop included tiers. Main will run everything eventually, just not on PR. Release branches could be changed to do the same thing.
There was a problem hiding this comment.
We need to explains:
- What these different "loops" are for / why they exist to enable others to make reasonable future changes to their pipeline definitions. It was not at all clear to me.
- Why they have different OSes in them and what informs that choice
- Any difference between main and release
We do not need to use tiers to do that. That was the most obvious approach.
Co-authored-by: Andy Gocke <[email protected]>
| - Tier 1: Azure Linux, Debian, Ubuntu (in inner and outer loop) | ||
| - Tier 2: Alpine and CentOS Stream (in inner loop) | ||
| - Tier 3: Fedora and OpenSUSE (in extra platforms) |
There was a problem hiding this comment.
| - Tier 1: Azure Linux, Debian, Ubuntu (in inner and outer loop) | |
| - Tier 2: Alpine and CentOS Stream (in inner loop) | |
| - Tier 3: Fedora and OpenSUSE (in extra platforms) | |
| - Tier 1: present in inner and outer loop (Azure Linux, Debian, Ubuntu) | |
| - Tier 2: present in inner loop only (Alpine and CentOS Stream) | |
| - Tier 3: present in extra platforms only (Fedora and OpenSUSE) | |
mainvsreleasebranches