Motivation

We continue to have lack of clarity within the division around what operating systems (OSes) we support for .NET, including details about how the environment look. The data is available but is located in multiple places (such as the official documentation (Windows, macOS and Linux platforms), OSOB YAML definitions, Kusto DB, AzDO pipelines) which makes it not suitable to be consumed by automation. We need to collect this information in a single place so it's available both to us and to our customers in forms that are readable both by humans (csvs, PowerBI reports) and by automation (e.g., JSON).

Additionally, there is not process in place that allows individual developers to see what OS versions are currently being considered for support and/or request support for a specific scenario they may have. Being able to provide clarity to the division and management on what OSes we support, in which environments and how we go about adding/removing support is the end goal for this epic.

The resulting processes, automation and produced data will be called "Matrix of Truth", abbreviated as "MoT" in the following description.

Business Objectives

The MoT initiative has two complementary aspects - process and tooling. Below are the business objectives for each of those aspects.

Process Objectives

The process and communication of changes to the fundamental underlying data of the MoT, such as what concrete versions of OSes are supported for a given version of .NET. The initial decisions about which OSes will be supported are made by the management and the PMs. Our responsibility is to define the mechanics of conveying, maintaining and presenting this information and their changes so that full audit trail (i.e., who changed what, when and why) is captured.

[x] Identify v-team membership - dnceng and partner teams
[x] Establish regular (monthly) sync for v-team
[ ] Document and share process for operating systems lifecycle for each type of OS (Linux, Windows, Mac) supported

Implementation Objectives

To get the full MoT picture, we will need to aggregate data from various sources in an automated way on a regular basis.

[x] Use-case scenarios for MoT are defined and reviewed by our partners
[x] System that aggregates data necessary to perform the identified scenarios in an automated manner is implemented
[x] Our customers can use the MoT data in automation (via JSON reports, etc.)
[x] Our customers can view and explore the MoT data in a human-readable form (xls, PowerBI report, etc.)
[x] The system ensures that full audit trail (who changed what, when and why) of the underlying fundamental data is kept

Scenarios

Together with our partners (discussed on Engineering Services Backlog Review on 03-Feb-2022), we have identified the following scenarios that will be performed by MoT users regularly. Each of the following scenarios represents a business objective to fulfill.

Roles

Platform Managers - Individuals responsible for managing the lifecycle of an Operating System for .NET (PM team, Leadership, DNCEng)
Customers - Anyone who builds/tests .NET

Initial OS Evaluation and Requests

Scenario	Process Implemented
Scenario 1 - As a customer or platform manager, I want to know what new Operating Systems are currently being evaluated and what the status of the approval process.	✅
Scenario 2 - As a customer or platform manager, I want to be able to request support for a new Operating System.	✅
Scenario 3 - As a platform manager, I want to be able to estimate infrastructure costs of onboarding a new Operating System based on utilization data of similar OSes.	✅
Scenario 4 - As a platform manager, I want to be able to see the overhead cost for supporting a new Operating System.	🔲
Scenario 5 - As a platform manager, I want to know the estimated release dates of upcoming new OS versions so that I can plan my future work.	✅

OS Onboarding and Adoption

Scenario	Data Collected	Included in Output	Shown on Report	Comments
Scenario 6 - As a platform manager, I want to track the progress of getting support for a new operating system and its adoption rate by the product teams.	✅	✅	✅

Querying Current State of Our Environment

Scenario	Data Collected	Included in Output	Shown on Report	Comments
Scenario 7 - As a customer or platform manager, I want to be able to see all the Operating Systems that are officially supported for version of .NET, so I can make sure that we have the correct coverage.	✅	✅	✅
Scenario 8 - As a customer, I want to see how each Operating System is supported in our environment (type of docker container / VM / physical machine, Operation System version, Build tools VS/XCODE version, Python version, etc.).	✅	✅	✅
Scenario 9 - As a customer or platform manager, I want to see what pipelines and/or repos are targeting each of the supported Operating Systems or Helix queues.	✅	✅	✅
Scenario 10 - As a platform manager, I want to see estimated utilization and time we spend for a given Operating System.	🔲	🔲	🔲	Based on discussion with @Chrisboh and @ilyas1974 we decided to postpone this scenario
Scenario 11 - As a platform manager, I want to see which product branches are targeting each of the supported Operating Systems.	✅	✅	✅
Scenario 12 - As a customer or platform manager, I want to see all Operating Systems which are approaching their EOL, so I can make sure my workloads are moved before an Operation System goes away.	✅	✅	✅
Scenario 13 - As a customer, I want to know all machine specifications which we run in our environment (physical machine, VM).	✅	✅	✅

OS Retirement and Removal

Scenario	Data Collected	Included in Output	Shown on Report	Comments
Scenario 14 - As a platform manager, I want to track the progress of removing support for an OS within our infrastructure.	✅	✅	✅
Scenario 15 - As a platform manager I want to see any differences between the official EOL date from the OEM and what our end of support date is	✅	✅	✅

Architecture

Milestones

[x] Identify business objectives in form of user scenarios and get feedback on them from our partners
[x] Design the internal data model that captures relationships of the fundamental entities (.NET versions, OSes, RIDs, Helix queues, 1ES, etc., docker) (30-January)
[x] https://github.com/dotnet/core-eng/issues/15677 (18-February)
[x] https://github.com/dotnet/core-eng/issues/15676 (25-February)
[x] Scenario 7, 8, 9 report review for March Engineering Services Backlog review (3-March)
[x] Implement report generation pipeline
[x] Collect usage telemetry (scenarios 3, 4, 10)
[x] Collect information about machine specification (scenario 13)
[x] Data collection, reports generation and process implementation for (TBD)
- [x] the rest of "Querying Current State of Our Environment" scenarios (end of March)
- [x] the "Initial OS Evaluation and Requests" scenarios (TBD)
- [x] the "OS Onboarding and Adoption" scenario (TBD)
- [x] https://github.com/dotnet/core-eng/issues/15668

dotnet / arcade

Create a single source of truth for our Platform Matrix #8832