From bc4971e4fcc8cae72b6f53659e890389cc705e53 Mon Sep 17 00:00:00 2001 From: Shankar Seal Date: Thu, 14 Mar 2024 22:36:51 -0700 Subject: [PATCH] Update the release process. --- docs/ReleaseProcess.md | 118 ++++++++++++++++++++--------------------- 1 file changed, 59 insertions(+), 59 deletions(-) diff --git a/docs/ReleaseProcess.md b/docs/ReleaseProcess.md index b34ac9bef2..ae088ec002 100644 --- a/docs/ReleaseProcess.md +++ b/docs/ReleaseProcess.md @@ -1,21 +1,23 @@ # Release Process -This file details the steps for creating a versioned release of -eBPF for Windows, and how to service it later. +This document outlines the steps to create, publish and service a release of eBPF for Windows. ->**Note**: Currently releases are *not* production signed and therefore considered as "pre-releases". Their versioning is currently fixed to *Major Version (i.e., "X")* set to "`0`", therefore versioned as "`0.Y.Z`". +The eBPF project follows [Semantic Versioning 2.0](https://semver.org) for versioning releases in the format `X.Y.Z`, where "`X`" and "`Y`" are the major and minor versions respectively. "`Z`" is the patch version for servicing releases. A release is usually made once every month. Pre-release binaries are test signed. Official releases will be production signed using Microsoft certificates. + +>**Note**: Currently the *major version* for all releases are set to "`0`" (i.e. "`0.Y.Z`") until the first official release is published with version `1.0.0`. ## Creating a new release -1. Create a working branch from "`main`" on your private repo fork, and check it out (e.g., `/release-X-Y-Z`). -1. Run the following script from the root directory of the repository, within a "*Developer Poweshell for VS 2022"* instance. Make sure to follow [Semantic Versioning 2.0](https://semver.org) ("`X.Y.Z`"): +An issue with the title `Scheduled eBPF release is due` is created on the first day of every month requesting for a new release with the minor version incremented every time. When this issue is triaged, a decision must be taken by the maintainers on whether to go ahead with the new monthly release. If the decision is to create a new release the release manager must proceed with the following process. +1. Create a topic branch from "`main`" on your private repo fork, and check it out (e.g., `/release-build`). +2. Run the following script from the root directory of the repository, from a "*Developer Powershell for VS 2022"* terminal. ```ps - # Replace "X.Y.Z" with the new version number being released - .\scripts\update-release-version.ps1 X Y Z + # Replace "X" and "Y" with the new major and minor versions: + .\scripts\update-release-version.ps1 X Y 0 ``` - A successful run of the script will produce output similar to the following: + For example, the successful run of the script for version 0.12.0 produces the following output: ```ps PS D:\work\ebpf-for-windows> .\scripts\update-release-version.ps1 0 12 0 @@ -25,29 +27,57 @@ eBPF for Windows, and how to service it later. Version number updated to '0.12.0' in D:\work\ebpf-for-windows\scripts\..\installer\Product.wxs Rebuilding the solution, please wait... Regenerating the expected 'bpf2c' output... - Generating output for atomic_instruction_fetch_add.o ... ... - Generating output for printk_unsafe.o Expected 'bpf2c' output regenerated. Please verify all the changes then submit the pull-request into the 'release/0.12' branch. ``` -1. Verify all the changes then commit all in the working branch. +4. Verify all the changes then commit all in the working branch. >NOTE: The formatting rules may complain about the formatting of the generated `.c` files from the script above. In this case, override them with the following (so they'll work with the `bpf2c_tests` verifying their content): >```bash >git commit --no-verify >``` -1. Create a **Draft** pull-request for your branch into the main repo's "`main`" branch (which you created in step 1), and title the PR as *"Release v`X.Y.Z`"* (replace "`X.Y.Z`" with the version number being released). -1. Once the CI/CD pipeline for the PR completes, download the "`ebpf-for-windows - MSI installer (Build-x64_Release)`" and "`ebpf-for-windows - NuGet package (Build-x64_Release)`" build artifacts +5. Create a **Draft** pull-request from your topic branch into the `main` branch of the upstream repo, with the title of the PR as *"Release v`X.Y.0`"* (replace "`X`" and "`Y`" with the version number being released). +6. Once the CI/CD pipeline for the PR completes, download the "`ebpf-for-windows - MSI installer (Build-x64_Release)`" and "`ebpf-for-windows - NuGet package (Build-x64_Release)`" build artifacts (accessible via the "`Actions`" tab on GitHub). -1. Extract the `*.nupkg` file, and rename it in the following format (replace "`X.Y.Z`" with the version number being released): +7. Extract the `*.nupkg` file, and rename it in the following format: + - `eBPF-for-Windows.X.Y.0.nupkg` +8. Mark the draft PR as "Ready for review". +9. Once the PR is approved and merged into the "`main`" branch, of the upstream `ebpf-for-windows` repo, create a new release branch from `main` from the **previous PR's commit**, and name it "`release/X.Y.`". +10. **IMPORTANT:** Once the release branch is created, no new feature work is allowed to be merged. However, bug fixes can be taken as deemed necessary by the maintainers and the release manager. Whenever applicable, these bug fixer should first be made in the main branch, and cherry-picked to the release branch. In case a bug-fix PRs are merged into the `release/X.Y` branch, the **latest commit** in the `release/X.Y` branch must be designated as the commit for the release. +11. Follow the process in the [Release Branch Validation](ReleaseProcess.md#release-branch-validation) to ensure the quality of the release branch. +1. In the triage meeting after successful creation of the release branch, the release manager must ask if any maintainer has any reasons to hold off the release. If not, move to the following steps. +4. The `sign-off` label will be added to the issue created in step 1 of the [Creating a new release](ReleaseProcess.md#creating-a-new-release) process. Next create a tag for the *latest commit on the `release/X.Y` branch*. The tag should reflect the version number being released and adhere to the following notation: "`Release-vX.Y.0`". +5. The tag creation will automatically trigger the "`CI/CD - Release validation`" workflow for the `release/X.Y` branch. In case of failure, Follow the process in the [Release Branch Validation](ReleaseProcess.md#release-branch-validation). +13. Publish the release as per the [Publishing a Release](ReleaseProcess.md#publishing-a-release) process. + +## Release Branch Validation + +The `CI/CD - Release validation` worfklow (`cicd-release-validation.yml`) is used to validate a release branch. It contains more tests than the regular CI/CD pipeline, including longer duration fuzz tests, fault injection tests, stress tests, performance tests etc. These tests can be manually scheduled. Release manager must run these tests on the release manager. Due to the non-deterministic nature of some of the tests, it is recommended that the tests are run at least three times on the branch. If any of the tests fail, the release manager must investigate the failure and follow up with issues in github. Once potential fixes are merged to the release branch repeat the process until the workflow completes successfully. + +## Publishing the Release to GitHub + +6. Go to the repo on GitHub and click on "``" and click on right the "`Create a new release`" link. +7. Click on the "`Choose a tag`" combo box and select the tag with version number for the release, as created earlier. +8. Fill in the release title as "`vX.Y.Z`". Note "`Z`" must be `0` for the monthly release. Otherwise, it should be the patch number. +9. Manually enter release notes or click "`Generate release notes`" and then edit as desired. +10. Attach the `.msi`, the (non-redist) `.nupkg`, the `Build-x64-[Release|Debug].zip` and the `Build-x64-native-only-[Release|Debug].X.Y.Z.zip` build (from the CI/CD artifacts), by dropping them in the "`Attach binaries by dropping them here or selecting them.`" area. For example, the file list for `v0.11.0` should be: + + - *Build-x64-native-only-Debug.0.11.0.zip* + - *Build-x64-native-only-Release.0.11.0.zip* + - *ebpf-for-windows.0.11.0.msi* + - *eBPF-for-Windows.0.11.0.nupkg* + - *Build-x64-Debug.zip* + - *Build-x64-Release.zip* + +11. Check the "`Set as a pre-release`" checkbox, unless the release is production-signed. +12. Once the uploads are complete, click "`Publish release`". + +## Publishing the Release to NuGet.org - - `eBPF-for-Windows.X.Y.Z.nupkg` -1. Submit the PR for review (from its draft state), and wait for it to be approved and merged into the main repo's "`main`" branch. -1. On the main `ebpf-for-windows` repo, create a new release branch from `main` **corresponding to the previous PR's commit**, name it "`release/X.Y`" (replace "X.Y" with the version number being released). -1. Publish the release as per the "[Publishing a Release](ReleaseProcess.md#publishing-a-release)" process. +Upload the (**non-redist**) `.nupkg` file to [NuGet.org](https://www.nuget.org/) (the metadata inside the `.nuget` package itself will automatically populate all the other form fields). -## Servicing a release +## Servicing a Release Servicing a release has two main scenarios: @@ -55,11 +85,11 @@ Servicing a release has two main scenarios: >NOTE: In servicing a release branch, **new features must not be added to the release branch**. Only patches or hot-fixes will be accepted. -1. On the main `ebpf-for-windows` repo, create and check out a new working branch from the `/release/X.Y` branch you want to service. -1. Run the following script from the root directory of the repository, within a "*Developer Poweshell for VS 2022"* instance. Make sure to follow [Semantic Versioning 2.0](https://semver.org) ("`X.Y.Z`"): +1. On the upstream `ebpf-for-windows` repo, create and check out a new topic branch from the `release/X.Y` branch you want to service. +1. Run the following script from the root directory of the repository, within a "*Developer Poweshell for VS 2022"* instance. ```ps - # Replace "X.Y.Z" with the new version number being released + # Replace "X", "Y" and "Z" with the new version number being released .\scripts\update-release-version.ps1 X Y Z ``` 1. Cherry pick the commits from `main` that you want to add to the release (patches/hot-fixes, etc.): @@ -76,10 +106,11 @@ Servicing a release has two main scenarios: >```bash >git commit --no-verify >``` -1. Create a **Draft** pull-request for your working branch into the main repo's "`release/X.Y`" branch, and title the PR as *"Release v`X.Y.Z`"* (replace "`X.Y.Z`" with the version number being released). +1. Create a **Draft** pull-request from the topic branch into the upstream repo's "`release/X.Y`" branch, and title the PR as *"Release v`X.Y.Z`"* where "`Z`" is the patch version. 1. Wait for the CI/CD pipeline for the PR to complete successfully. -1. Submit the PR for review (from its draft state), and wait for it to be approved and merged into the main repo's "`release/X.Y`" branch. -1. Publish the release as per the "[Publishing a Release](ReleaseProcess.md#publishing-a-release)" process. +1. Mark the draft PR as "Ready for review". +3. Once the PR is approved and merged into the "`release/X.Y`" branch in the upstream repo, create a tag for the latest commit as "`Release-vX.Y.Z`". +4. Publish the patch release as per the [Publishing a Release](ReleaseProcess.md#publishing-a-release) process. ### Updating the main brach with patches/hot-fixes from a Release branch (*Reverse/Backwards Integration*) @@ -99,37 +130,6 @@ Servicing a release has two main scenarios: 1. Commit all the changes in the working branch. 1. Create a **Draft** pull-request for your working branch into the main repo's "`main`" branch, and title the PR as *"Backwards Integration of Release v`X.Y.Z`"* (replace "`X.Y.Z`" with the version number being released). 1. Wait for the CI/CD pipeline for the PR to complete successfully. -1. Submit the PR for review (from its draft state), and wait for it to be approved and merged into the main repo's "`main`" branch. -1. Create a tag for the PR's commit number, on the main repo's "`main`" branch, with meaningful name (i.e., "*RI-from-release-vX.Y.Z*"). - -## Publishing a Release - -As a result of creating new release or servicing an existing one, the following steps are required to publish the release: - -### Publishing the Release to GitHub - -1. On the `microsoft/ebpf-for-windows` repo's `main` branch, create a tag for the release-PR's commit. The tag should reflect the version number being released and adhere to the following notation: "`vX.Y.Z`". -1. Wait for the `sign-off` label to be added from the Triage meeting, on the automated "release-issue" associated to the release to be published. - >**IMPORTANT:** While awaiting sign-off, **only bug-fix PRs are allowed into the `release/X.Y` branch**. In case bug-fix PRs are merged into the `release/X.Y` branch, it is crucial to **designate the latest commit `release/X.Y` branch as the commit for release**. -1. Once the `sign-off` label has been added, on the `microsoft/ebpf-for-windows` repo's `release/X.Y` branch, create a tag for the *latest commit on the `release/X.Y` branch*. The tag should reflect the version number being released and adhere to the following notation: "`Release-vX.Y.Z`". -1. The tag creation will automatically trigger the "`CI/CD - Release validation`" workflow for the `release/X.Y` branch: wait for it to complete successfully. - >**NOTE:** If the release validation fails, it is the responsibility of the release manager to trigger further investigations, including eventually the submission of necessary issues. Once the issue(s) is(are) resolved, potentially through other PRs, it is important to **delete the previous tag**. Subsequently, recreate the same tag for the *latest commit* on the `release/X.Y` branch, wait for the "`CI/CD - Release validation`" workflow to complete successfully. -1. Go to the repo on GitHub and click on "``" and click on right the "`Create a new release`" link. -1. Click on the "`Choose a tag`" combo box and select the tag with new "`Release vX.Y.Z`" version number, as created earlier. -1. Fill in the release title as "`vX.Y.Z`" (replace "`X.Y.Z`" with the version number being released). -1. Manually enter release notes or click "`Generate release notes`" and then edit as desired. -1. Attach the `.msi`, the (non-redist) `.nupkg`, the `Build-x64-[Release|Debug].zip` and the `Build-x64-native-only-[Release|Debug].X.Y.Z.zip` build (from the CI/CD artifacts), by dropping them in the "`Attach binaries by dropping them here or selecting them.`" area. For example, the file list for `v0.11.0` should be: - - - *Build-x64-native-only-Debug.0.11.0.zip* - - *Build-x64-native-only-Release.0.11.0.zip* - - *ebpf-for-windows.0.11.0.msi* - - *eBPF-for-Windows.0.11.0.nupkg* - - *Build-x64-Debug.zip* - - *Build-x64-Release.zip* - -1. Check the "`Set as a pre-release`" checkbox, unless the release is production-signed. -1. Once the uploads are complete, click "`Publish release`". - -### Publishing the Release to NuGet.org - -Upload the (**non-redist**) `.nupkg` file to [NuGet.org](https://www.nuget.org/) (the metadata inside the `.nuget` package itself will automatically populate all the other form fields). +1. Mark the draft PR as "Ready for review". +3. Submit the PR for review (from its draft state), and wait for it to be approved and merged into the main repo's "`main`" branch. +4. Create a tag for the PR's commit number, on the main repo's "`main`" branch, with meaningful name (i.e., "*RI-from-release-vX.Y.Z*").