From 98a4bc3f90392cdd154f1d9b3f5e7890420d71ae Mon Sep 17 00:00:00 2001 From: Ella Hathaway Date: Tue, 10 Jun 2025 23:22:59 +0000 Subject: [PATCH] Add information on how to update distro versions in the VMR --- .../ci-platform-coverage-guidelines.md | 73 +++++++++++++++++-- 1 file changed, 67 insertions(+), 6 deletions(-) diff --git a/Documentation/ci-platform-coverage-guidelines.md b/Documentation/ci-platform-coverage-guidelines.md index e27504850d..366dcb2e38 100644 --- a/Documentation/ci-platform-coverage-guidelines.md +++ b/Documentation/ci-platform-coverage-guidelines.md @@ -44,10 +44,71 @@ matrix](https://github.com/dotnet/sdk/blob/main/eng/pipelines/templates/stages/v 1. Alpine - Latest version (amd64) 1. AlmaLinux - Oldest version (targets lowest glibc version) (amd64) -When updating the distro versions in the CI matrix as new versions are released -and older versions reach EOL: +## Updating Distro Versions in the VMR -1. Update `main` to the newer version one to two months prior to the GA/EOL date. - This is done to flush out any issues and to avoid destabilizing the servicing - branches. -1. At the GA/EOL date, update the servicing branches. +There are two scenarios when updating distro versions in the CI pipeline: + +### Case 1: OS Used in N-1 Leg (Previous Version Support) + +When updating a distro that is used in a n-1 (previous version) build leg: + +1. Update pipeline build configuration variables + +1. Create backup pipeline RID variable for old version: + - Create a new distro RID variable with suffix `Old` + (eg. if current variable is `centOSStreamX64Rid`, create `centOSStreamX64RidOld`) + - Set the value to the RID of the old distro version being replaced + +1. File tracking issue: + - Create an issue in [dotnet/source-build](https://github.com/dotnet/source-build) repository + - Title should indicate need to update artifacts RID after next rebootstrap or release + - This ensures the old RID is properly cleaned up later + +1. Update n-1 build legs: + - Change the `artifactsRid` template parameter for n-1 build legs to use the `Old` variable + - Add a comment with a link to the issue created in step 3 + +1. Update prep-source-build.sh: + - Add a comment above the [`defaultArtifactsRid`](https://github.com/dotnet/dotnet/blob/604a6612d130bc042dc973aba84889f529f9cb69/prep-source-build.sh#L40) variable to update the default value + - Include a link to the issue created in step 3 + +1. Submit changes: + - Open a pull request with all the above changes + - Ensure all changes are reviewed and tested by doing a full run of the VMR + - 8.0/9.0: [dotnet-source-build-pre10.0](https://dev.azure.com/dnceng/internal/_build?definitionId=1219) + - 10.0+: [dotnet-unified-build](https://dev.azure.com/dnceng/internal/_build?definitionId=1330) + +1. Update release pipeline infrastructure: + - After the public PR is merged, update [the leg name(s)](https://dev.azure.com/dnceng/internal/_git/dotnet-release?path=/eng/pipeline/source-build-release/steps/re-bootstrap.yml&version=GBmain&line=68&lineEnd=86&lineStartColumn=1&lineEndColumn=1&lineStyle=plain&_a=contents) for the release artifacts to match the new configuration in the VMR + - Create and merge this PR to complete the update process + +1. Close tracking issue from step 3: + - After the subsequent release or reboostrap (whichever comes first), + open a PR with the changes linked to the tracking issue from step 3. + - Merge the changes, and close the issue + +### Case 2: Regular Artifact (Standard Update) + +For distros not used in n-1 legs (simpler case): + +1. Update build configuration variables +1. Submit changes: + - Open a pull request with all the above changes + - Ensure all changes are reviewed and tested by doing a full run of the VMR + - 8.0/9.0: [dotnet-source-build-pre10.0](https://dev.azure.com/dnceng/internal/_build?definitionId=1219) + - 10.0+: [dotnet-unified-build](https://dev.azure.com/dnceng/internal/_build?definitionId=1330) + +## Timing Guidelines for Distro Updates + +When updating distro versions as new versions are released and older versions reach end-of-life (EOL): + +1. **Pre-GA/EOL updates (1-2 months before):** + - Update the `main` branch to use the newer distro version + - This allows time to identify and resolve any compatibility issues + - Helps avoid destabilizing servicing branches close to release dates + - Follow guidelines described in [Permutations](#permutations) + +2. **GA/EOL date updates:** + - Update all active servicing branches (`release/x.0` branches) + - Ensure consistency across all supported .NET versions + - Follow guidelines described in [Permutations](#permutations)