This document provides a guide on how to release a preview of YARP.
To keep track of the process, open a release checklist issue.
Ensure the eng/Versions.props file has the expected versions and pre-release labels. For a final release set PreReleaseVersionLabel to rtw.
See Branching:
- Make the next preview branch.
- Update the branding in main.
- Update the global.json runtime and SDK versions in main.
First, identify the final build of the microsoft-reverse-proxy-official Azure Pipeline (on dnceng/internal). The final build will be the latest successful build in the relevant release/x branch. Use the "Branches" tab on Azure DevOps to help identify it. If the branch hasn't been mirrored yet (see code-mirror pipeline) and there are no outstanding changesets in the branch, the build of the corresponding commit from the main branch can be used.
Once you've identified that build, click in to the build details.
At this point, you can perform any validation that makes sense. At a minimum, we should validate that the sample can run with the candidate packages. You can download the final build using the "Artifacts" which can be accessed under "Related" in the header:
The packages can be accessed from the PackageArtifacts artifact:
- Visual Studio: Place it in a local folder and add that folder as a nuget feed in Visual Studio.
- Command Line:
dotnet nuget add source <directory> -n local
Walk through the Getting Started instructions and update them in the release branch as needed.
Also validate any major new scenarios this release and their associated docs.
Once validation has been completed, it's time to release. Go back to the Final Build in Azure DevOps. It's probably good to triple-check the version numbers of the packages in the artifacts against whatever validation was done at this point.
Select "Release" from the triple-dot menu in the top-right of the build details page:
Verify the Release Pipeline selected is microsoft-reverse-proxy-release, that the NuGet.org stage has a blue border (meaning it will automatically deploy) and that the build number under Artifacts matches the build number of the final build (it will not match the package version). The defaults selected by Azure Pipelines should configure everything correctly but it's a good idea to double check.
Click "Create" to start the release! Unless you're a release approver, you're done here!
The Azure Pipeline will send an email to all the release approvers asking one of them to approve the release:
Click "View Approval", or navigate to the release directly in Azure DevOps. You'll see that the stage is "Pending Approval"
Click "Approve" to bring up the Approval dialog. Enter a comment such as "release for preview X" and click "Approve" to finalize the release. After pressing "Approve", packages will be published automatically. It is possible to cancel the pipeline, but it might be too late. See "Troubleshooting" below.
Click "Reject" to cancel the release.
The packages will be pushed and when the "NuGet.org" stage turns green, the packages are published!
Note: NuGet publishing is quick, but there is a background indexing process that can mean it will take up to several hours for packages to become available
Create and push a git tag for the commit associated with the final build (not necessarily the HEAD of the current release branch). See prior tags for the preferred format. Use a lightweight tag, not annotated.
git tag v1.0.0-previewX
Push the tag change to the upstream repo (not your fork)
git push upstream --tags
Create a draft release at https://github.com/microsoft/reverse-proxy/releases using the new tag. See prior releases for the recommended content and format.
Projects in the samples folder use PackageReference on the release branch and ProjectReference on the main branch.
Update all project files in the samples folder on the release branch to use PackageReference with the newly-released version. Make sure the samples are buildable after this change.
Reset the release/latest branch to the head of the current preview branch to publish the latest docs. See docs.
Publish the draft release notes. These should be referencing the latest docs, packages, etc..
It should be empty now. If it's not, move the outstanding issues to the next one.
David Fowler has a lot of twitter followers interested in YARP. Tweet a link to the release notes and let him retweet it.
This is to avoid accidental pushes to/deletions of the preview branch.
There should only be one preview branch on the repo after this point.
- Go to the internal https://dpsopsrequestforms.azurewebsites.net portal
- Select "Source Code Archival"
- Proceed through steps 1,2 till the step 3 (all prerequisites are already fulfilled)
- Fill in the required fields on the steps 3, 4, 5. Please, see the recommended values below.
- At the last step, check all the info and and submit the request
- Go to "My Request" tab and wait for a new ticket to appear on the list
- Copy the ticket link from "Ticket ID" column which will look like
https://prod.****** - Replace the
prodword toportal - Navigate to the fixed link and check that the ticket is actually created
- That's all the actions needed to be done immediately. Afterwards, periodically track the ticket progress. It might take many hours.
- [Offline] Wait for the archival completion report to arrive. Check that the size and number of archived files match the YARP repo.
| Field | Value |
|---|---|
| Team Alias | dotnetrp |
| Business Group Name | Devdiv |
| Product Name | YARP |
| Version | <release version> |
| Production Type | dotNET |
| Release Type | <RC or Release> |
| Operating System(s) | Cross Platform |
| Product Language(s) | English |
| Release Date | <release date> |
| File Count | <rough number of files in repo> |
| Back Up Type | Code Repo(Git URL/AzureDevOps) |
| Repo URL | <link to the internal AzDo YARP repo> |
| OwnerAlias | dotnetrp |
| File Collection | Build Scripts, Help Utility Source Code, Source Code |
| Data Size | <rough total files size in MB> |
The pipeline is authenticated via a "Service Connection" in Azure DevOps. If there are authentication errors, it's likely the API key is invalid. Follow these steps to update the API key:
- Go to NuGet.org, log in with an account associated with an
@microsoft.comaddress that has access to thedotnetframeworkorganization. - Generate a new API key with "dotnetframework" as the Package Owner and "*" as the Package "glob".
- Copy that API key and fill it in to the "nuget.org (dotnetframework organization)" Service Connection in Azure DevOps.
In the event you don't have access, contact [email protected] for guidance.
In the event you overpublish (publish a package that wasn't intended to be released), you should "unlist" the package on NuGet. It is not possible to delete packages on NuGet.org, by design, but you can remove them from search results. Users who reference the version you published directly will still be able to download it, but it won't show up in search queries or non-version-specific actions (like installing the latest).
- Go to NuGet.org, log in with an account associated with an
@microsoft.comaddress that has access to thedotnetframeworkorganization. - Go to the package page and click "Manage package" on the "Info" sidebar on the right.
- Expand "Listing"
- Select the version that was accidentally published
- Uncheck the "List in search results" box
- Click "Save"
NuGet.org has special criteria for all packages starting Microsoft.. If the package is rejected for not meeting one of those criteria, go to the NuGet @ Microsoft page for more information on required criteria and guidance for how to configure the package appropriately.