diff --git a/Documentation/ci-platform-coverage-guidelines.md b/Documentation/ci-platform-coverage-guidelines.md index e27504850d..12adc809ad 100644 --- a/Documentation/ci-platform-coverage-guidelines.md +++ b/Documentation/ci-platform-coverage-guidelines.md @@ -44,8 +44,55 @@ 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 - [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 - [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) + +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) - [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) + +For distros not used in n-1 legs: + +1. **Update VMR pipeline variables:** + - 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) + +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