diff --git a/docs/Governance.md b/docs/Governance.md index 7a7e82d258..e66d32f2ea 100644 --- a/docs/Governance.md +++ b/docs/Governance.md @@ -64,7 +64,7 @@ A maintainer can also merge pull requests. This corresponds to the "Write" role in github. All maintainers should be be listed in the [CODEOWNERS file](../.github/CODEOWNERS). -Personnel: @Alan-Jowett @dv-msft @matthewige @mtfriesen @rectified95 @saxena-anurag @shpalani +Personnel: @Alan-Jowett @dv-msft @gtrevi @matthewige @mtfriesen @rectified95 @saxena-anurag @shpalani Minimum Requirements: * Consistently participates in weekly [triage meetings](https://github.com/microsoft/ebpf-for-windows/discussions/427) @@ -81,6 +81,7 @@ Responsibilities: In addition to having Maintainer privileges and responsibilities, a release manager is also responsible for generating releases in github. +The release manager for this project must be a Microsoft full time employee. Personnel: @gtrevi @shpalani @matthewige diff --git a/docs/ReleaseProcess.md b/docs/ReleaseProcess.md index ae088ec002..e96fa498a7 100644 --- a/docs/ReleaseProcess.md +++ b/docs/ReleaseProcess.md @@ -2,7 +2,7 @@ This document outlines the steps to create, publish and service a release of eBPF for Windows. -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. +The eBPF project follows [Semantic Versioning 1.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`. @@ -10,46 +10,41 @@ The eBPF project follows [Semantic Versioning 2.0](https://semver.org) for versi 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. +1. Run the following script from the root directory of the repository, from a "*Developer Powershell for VS 2022"* terminal. ```ps # Replace "X" and "Y" with the new major and minor versions: .\scripts\update-release-version.ps1 X Y 0 ``` - For example, the successful run of the script for version 0.12.0 produces the following output: + For example, the successful run of the script for version 0.11.0 produces the following output: ```ps PS D:\work\ebpf-for-windows> .\scripts\update-release-version.ps1 0 12 0 Updating the version number in the 'D:\work\ebpf-for-windows\scripts\..\resource\ebpf_version.h' file... - Version number updated to '0.12.0' in D:\work\ebpf-for-windows\scripts\..\resource\ebpf_version.h + Version number updated to '0.11.0' in D:\work\ebpf-for-windows\scripts\..\resource\ebpf_version.h Updating the version number in the 'D:\work\ebpf-for-windows\scripts\..\installer\Product.wxs' file... - Version number updated to '0.12.0' in D:\work\ebpf-for-windows\scripts\..\installer\Product.wxs + Version number updated to '0.11.0' in D:\work\ebpf-for-windows\scripts\..\installer\Product.wxs Rebuilding the solution, please wait... Regenerating the expected 'bpf2c' output... ... ... Expected 'bpf2c' output regenerated. - Please verify all the changes then submit the pull-request into the 'release/0.12' branch. + Please verify all the changes then submit the pull-request into the 'release/0.11' branch. ``` -4. Verify all the changes then commit all in the working branch. +1. 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 >``` -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). -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. +1. Create a pull-request from your topic branch into the `main` branch of the original repo, with the title of the PR as *"Release v`X.Y.0`"* (replace "`X`" and "`Y`" with the version number being released). +1. Once the PR is approved and merged into the "`main`" branch, of the original `ebpf-for-windows` repo, create a new release branch from `main` from the **previous PR's commit**, and name it "`release/X.Y.`". +1. **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. +1. 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`". +1. 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). +11. Publish the release as per the [Publishing a Release](ReleaseProcess.md#publishing-a-release) process. ## Release Branch Validation @@ -57,21 +52,24 @@ The `CI/CD - Release validation` worfklow (`cicd-release-validation.yml`) is use ## 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: +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 version number for the release, as created earlier. +1. 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. +1. Manually enter release notes or click "`Generate release notes`" and then edit as desired. +1. Microsoft maintains an internal mirror of the eBPF for Windows project. For a given release branch in github, the mirror repo will have a corresponding one. The release manager must download the "`ebpf-for-windows - MSI installer (Build-x64_Release)`" and "`ebpf-for-windows - NuGet package (Build-x64_Release)`" build artifacts + from the Microsoft internal repository's build pipeline. Extract the `*.nupkg` file from it, and rename it to `eBPF-for-Windows.X.Y.0.nupkg` + - **NOTE** : The Microsoft internal build pipeline has two flavors of nuget package. The release manager must pick the one that *does not* contain "Redist" in the name. +1. Attach the `Build-x64-[Release|Debug].zip`, the `Build-x64-native-only-[Release|Debug].X.Y.Z.zip`, the `.msi`, and the `.nupkg`, 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-Debug.zip* + - *Build-x64-Release.zip* - *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`". +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 @@ -85,7 +83,7 @@ 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 upstream `ebpf-for-windows` repo, create and check out a new topic branch from the `release/X.Y` branch you want to service. +1. On the original `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 @@ -106,11 +104,9 @@ Servicing a release has two main scenarios: >```bash >git commit --no-verify >``` -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. 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. +1. Create a pull-request from the topic branch into the original repo's "`release/X.Y`" branch, and title the PR as *"Release v`X.Y.Z`"* where "`Z`" is the patch version. +1. Once the PR is approved and merged into the "`release/X.Y`" branch in the original repo, create a tag for the latest commit as "`Release-vX.Y.Z`". +1. 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*) @@ -131,5 +127,4 @@ Servicing a release has two main scenarios: 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. 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*"). +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.