Skip to content

Document the Distro Upgrade Process #5239

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
Jul 29, 2025
Merged

Document the Distro Upgrade Process #5239

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
f458e66
Document distro upgrade process
ellahathaway Jul 28, 2025
9ef4040
Fix linter error
ellahathaway Jul 28, 2025
b49a386
Add examples
ellahathaway Jul 28, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
51 changes: 49 additions & 2 deletions Documentation/ci-platform-coverage-guidelines.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down