From f458e66daffaade44935f03a196d48f4bce0d1ed Mon Sep 17 00:00:00 2001 From: Ella Hathaway Date: Mon, 28 Jul 2025 18:14:35 +0000 Subject: [PATCH 1/3] Document distro upgrade process --- .../ci-platform-coverage-guidelines.md | 52 ++++++++++++++++++- 1 file changed, 50 insertions(+), 2 deletions(-) diff --git a/Documentation/ci-platform-coverage-guidelines.md b/Documentation/ci-platform-coverage-guidelines.md index e27504850d..539b14f201 100644 --- a/Documentation/ci-platform-coverage-guidelines.md +++ b/Documentation/ci-platform-coverage-guidelines.md @@ -44,8 +44,56 @@ 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 + +There are two scenarios when updating distro versions in the CI pipeline: + +### Case 1: OS Leg in VMR Produces N-1 artifact (Previous Version Support) + +When updating a distro that produces an N-1 (previous version) artifact in the VMR: + +1. **Update VMR pipeline variables:** + - Create "Previous" versions of existing distro variables by adding `Previous` suffix to preserve the old values + - Update current distro variables to new version values + +1. **Update VMR pipeline:** + - Add container configuration for previous version + - For previous legs, update the distro parameters to use the previous variables you created in Step 1. + +1. **Update SBRP Cleanup pipeline:** + - If applicable, update the default artifact name in the source-build-reference-packages clean up pipeline - [example](https://github.com/dotnet/source-build-reference-packages/pull/1284) + +1. **File a tracking issue** to remove the previous variables and update the artifact RID used in `prep-source-build.sh` - [example](https://github.com/dotnet/source-build/issues/5238) + +1. **Submit and test your changes:** + - Open a pull request with all changes - [example](https://github.com/dotnet/dotnet/pull/1093) + - Queue a full build of the VMR to validate the changes + +1. **Update release pipelines:** + - Update the artifact name for relevant .NET version in the source-build release and re-bootstrap pipeline - [example](https://dev.azure.com/dnceng/internal/_git/dotnet-release/commit/c9be53307205765ebae48c18d00ef6260e596817?path=/eng/pipeline/source-build-release/steps/re-bootstrap.yml&version=GBmain&line=90&lineEnd=91&lineStartColumn=1&lineEndColumn=1&type=2&lineStyle=plain&_a=files). + - The release validation will fail until the next source-build release. File an issue to update the artifacts used for the release validation after the next release. + +1. **Complete the transition:** + - Queue the re-bootstrap pipeline after the next successful CI build of the VMR + - In the resulting PR, make the changes described in your tracking issue (Step 4) + - Merge the resulting PR and close the tracking issue + + +### Case 2: OS Leg in VMR Produces Regular Artifact (Standard Update) + +For distros not used in n-1 legs: + +1. **Update VMR pipeline variables:** + - Update the distro-specific variables to new version values + +1. **Update SBRP Cleanup pipeline:** + - If applicable, update default artifact name in the source-build-reference-packages clean up pipeline - [example](https://github.com/dotnet/source-build-reference-packages/pull/1284) + +1. **Submit changes:** + - Open a pull request with all the above changes + - Queue a full build of the VMR to validate the changes + +## Timing Guidelines for Distro Updates 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 From 9ef40400595312350d843af0f7e5a43dee939053 Mon Sep 17 00:00:00 2001 From: Ella Hathaway Date: Mon, 28 Jul 2025 18:33:59 +0000 Subject: [PATCH 2/3] Fix linter error --- Documentation/ci-platform-coverage-guidelines.md | 1 - 1 file changed, 1 deletion(-) diff --git a/Documentation/ci-platform-coverage-guidelines.md b/Documentation/ci-platform-coverage-guidelines.md index 539b14f201..9a49e454e4 100644 --- a/Documentation/ci-platform-coverage-guidelines.md +++ b/Documentation/ci-platform-coverage-guidelines.md @@ -78,7 +78,6 @@ When updating a distro that produces an N-1 (previous version) artifact in the V - In the resulting PR, make the changes described in your tracking issue (Step 4) - Merge the resulting PR and close the tracking issue - ### Case 2: OS Leg in VMR Produces Regular Artifact (Standard Update) For distros not used in n-1 legs: From b49a3869d4e0b5bee2ca7aefcdedcf4bdd53fdec Mon Sep 17 00:00:00 2001 From: Ella Hathaway Date: Mon, 28 Jul 2025 20:06:51 +0000 Subject: [PATCH 3/3] Add examples --- Documentation/ci-platform-coverage-guidelines.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/Documentation/ci-platform-coverage-guidelines.md b/Documentation/ci-platform-coverage-guidelines.md index 9a49e454e4..12adc809ad 100644 --- a/Documentation/ci-platform-coverage-guidelines.md +++ b/Documentation/ci-platform-coverage-guidelines.md @@ -53,12 +53,12 @@ There are two scenarios when updating distro versions in the CI pipeline: When updating a distro that produces an N-1 (previous version) artifact in the VMR: 1. **Update VMR pipeline variables:** - - Create "Previous" versions of existing distro variables by adding `Previous` suffix to preserve the old values - - Update current distro variables to new version values + - Create "Previous" versions of existing distro variables by adding `Previous` suffix to preserve the old values - [example](https://github.com/ellahathaway/dotnet/blob/12c9fccc3192d5bbf9f98ea15cedcdcf55334f89/eng/pipelines/templates/variables/vmr-build.yml#L117-L121) + - Update current distro variables to new version values - [example](https://github.com/dotnet/dotnet/pull/1093/files#diff-821e317646a065ee331aa7444ca5e2ae9f76512e5ca316e045280e526db23724R192-R193) 1. **Update VMR pipeline:** - - Add container configuration for previous version - - For previous legs, update the distro parameters to use the previous variables you created in Step 1. + - Add container configuration for previous version - [example](https://github.com/ellahathaway/dotnet/blob/12c9fccc3192d5bbf9f98ea15cedcdcf55334f89/eng/pipelines/ci.yml#L94-L96) + - For previous legs, update the distro parameters to use the previous variables you created in Step 1 - [example](https://github.com/ellahathaway/dotnet/blob/12c9fccc3192d5bbf9f98ea15cedcdcf55334f89/eng/pipelines/templates/stages/source-build-and-validate.yml#L33-L38) 1. **Update SBRP Cleanup pipeline:** - If applicable, update the default artifact name in the source-build-reference-packages clean up pipeline - [example](https://github.com/dotnet/source-build-reference-packages/pull/1284) @@ -75,7 +75,7 @@ When updating a distro that produces an N-1 (previous version) artifact in the V 1. **Complete the transition:** - Queue the re-bootstrap pipeline after the next successful CI build of the VMR - - In the resulting PR, make the changes described in your tracking issue (Step 4) + - In the resulting PR, make the changes described in your tracking issue (Step 4) - [example](https://github.com/dotnet/dotnet/pull/1187/commits/622843880cb3fb0c78896b1c9b5ef76b2a114017) - Merge the resulting PR and close the tracking issue ### Case 2: OS Leg in VMR Produces Regular Artifact (Standard Update) @@ -83,7 +83,7 @@ When updating a distro that produces an N-1 (previous version) artifact in the V For distros not used in n-1 legs: 1. **Update VMR pipeline variables:** - - Update the distro-specific variables to new version values + - Update the distro-specific variables to new version values - [example](https://github.com/dotnet/dotnet/pull/1093/files#diff-821e317646a065ee331aa7444ca5e2ae9f76512e5ca316e045280e526db23724R192-R193) 1. **Update SBRP Cleanup pipeline:** - If applicable, update default artifact name in the source-build-reference-packages clean up pipeline - [example](https://github.com/dotnet/source-build-reference-packages/pull/1284)