diff --git a/docs/contributing/contributing-releases/README.md b/docs/contributing/contributing-releases/README.md index 7858da7083..43984d8198 100644 --- a/docs/contributing/contributing-releases/README.md +++ b/docs/contributing/contributing-releases/README.md @@ -23,11 +23,10 @@ The `versions.yaml` file is a declarative version tracking file that the Radius ### Test tutorials and samples -In the project-radius/samples repo, run the [Test Quickstarts](https://github.com/project-radius/samples/actions/workflows/test.yaml) workflow. +In the project-radius/samples repo, run the [Test Quickstarts](https://github.com/project-radius/samples/actions/workflows/test.yaml) workflow. > For now, this is a manual task. Soon, this workflow will be triggered automatically. - -> There is a possibility that the workflow run failed from flaky tests. Try re-running, and if the failure is persistent, then there should be further investigation. +> There is a possibility that the workflow run failed because of flaky tests. Try re-running, and if the failure is persistent, then there should be further investigation. If this workflow run fails, or if we encounter an issue with an RC release, please refer to "Patching" below. @@ -37,21 +36,14 @@ If sample validation passes, we can start the process of creating the final rele 1. Go through steps 1-4 of "Creating an RC release" above, substituting the final release version instead of the RC version. For example, if the RC version number is `0.1.0-rc1`, the final release version would be `0.1.0`. -1. After creating the pull request, there should be an automatically-generated release notes comment. Create a new release note document in the [release-notes](../../release-notes/) directory. Follow the directory's README.md for instructions on how to create a new release note document. Include this file in the release version pull request. [Example](https://github.com/project-radius/radius/pull/6092/files) +1. After creating the pull request, there should be an automatically generated release notes comment. Create a new release note document in the [release-notes](../../release-notes/) directory. Follow the directory's README.md for instructions on how to create a new release note document. Include this file in the release version pull request. [Example](https://github.com/project-radius/radius/pull/6092/files) 1. Cherry-pick the `version.yaml` changes and the release notes into the release branch. This will ensure that the version changes and release notes are included in the release branch. [Example](https://github.com/radius-project/radius/pull/6114/files) + ```bash git cherry-pick -x ``` -1. Purge the [CDN cache](https://ms.portal.azure.com/#@microsoft.onmicrosoft.com/resource/subscriptions/66d1209e-1382-45d3-99bb-650e6bf63fc0/resourcegroups/assets/providers/Microsoft.Cdn/profiles/Radius/endpoints/radius/overview). - ```bash - $ az login - $ az cdn endpoint purge --subscription 66d1209e-1382-45d3-99bb-650e6bf63fc0 --resource-group assets --name radius --profile-name Radius --content-paths "/*" - ``` - - For now, this is a manual task. Soon, this will be automated. - 1. In the project-radius/docs repository, run the [Release docs](https://github.com/project-radius/docs/actions/workflows/release.yaml) workflow. 1. In the project-radius/docs repository, run the [Release samples](https://github.com/project-radius/samples/actions/workflows/release.yaml) workflow. @@ -60,49 +52,52 @@ If sample validation passes, we can start the process of creating the final rele ## How releases work -Each release belongs to a *channel* named like `.`. Releases will only interact with assets from their channel. For example, the `0.1` `rad` CLI will: +Each release belongs to a *channel* named `.`. Releases will only interact with assets from their channel. For example, the `0.1` `rad` CLI will: - Download `rad-bicep` from the `0.1` channel - Create an environment using the `0.1` version of the RP and environment setup script -> ⚠️ Compatibility ⚠️
+> ⚠️ Compatibility ⚠️ At this time we do not guarantee compatibility across releases or provide a migration path. For example, the behavior of a `0.1` `rad` CLI talking to a `0.2` control plane is unspecifed. We expect the project to change too frequently to provide compatibility guarantees at this time. Conceptually we scope channels to a major+minor pair because this allows us to freely patch assets as needed without needing to change the intermediate pieces. For example pushing a `v0.1.1` tag will update the assets in the `v0.1` channel. This works as long as it is a *true* patch release and maintains compatibility. ## Patching -Let's say we have a bug in a release which needs to be patched for an already created release. +Let's say we have a bug in a release that needs to be patched for an already-created release. 1. Go through steps 1-4 of "Creating an RC release" above on the `main` branch, substituting the patch release version instead of the final release version. For example, if the final release version number is 0.1.0, the patch release version would be 0.1.1. -1. After creating the pull request, there should be an automatically-generated release notes comment. Create a new release note document in the [release-notes](../../release-notes/) directory. Follow the directory's README.md for instructions on how to create a new patch release note document. Include this file in the release version pull request. [Example](https://github.com/project-radius/radius/pull/6092/files) +1. After creating the pull request, there should be an automatically generated release notes comment. Create a new release note document in the [release-notes](../../release-notes/) directory. Follow the directory's README.md for instructions on how to create a new patch release note document. Include this file in the release version pull request. [Example](https://github.com/project-radius/radius/pull/6092/files) + +1. Now we can start patching the release branch. Make sure the commit that we want to add to a patch is merged and validated in `main` first if it affects `main`. -1. Now we can start patching the release branch. Make sure the commit that we want to add to a patch is merged and validate in `main` first if it affects `main`. +1. Create a new branch based off of the release branch we want to patch. Ex: -1. Create a new branch based off the release branch we want to patch. Ex: ```bash git checkout release/0. git checkout -b / ``` 1. Cherry-pick the commit that is on `main` onto the branch. PLEASE USE `-x` HERE TO ENSURE VERSION HISTORY IS PRESERVED. + ```bash git cherry-pick -x ``` -1. If breaking changes have been made to our Bicep fork: - - Update the file radius/.github/workflows/validate-bicep.yaml to use the release version (eg. v0.21) instead of edge for validating the biceps in the docs and samples repositories. Also modify the version from `env.REL_CHANNEL` to `.` (eg. `0.21`) for downloading the `rad-bicep-corerp`. +1. If breaking changes have been made to our Bicep fork: + + Update the file radius/.github/workflows/validate-bicep.yaml to use the release version (eg. v0.21) instead of edge for validating the biceps in the docs and samples repositories. Also, modify the version from `env.REL_CHANNEL` to `.` (eg. `0.21`) for downloading the `rad-bicep-corerp`. -1. Cherry-pick the `version.yaml` changes and release notes onto the branch from the PR opened against main. This will ensure that the release notes are included in the release branch. [Example](https://github.com/radius-project/radius/pull/6114/files). The release branch should now contain all needed patch changes, an updated release version, and patch release notes. +1. Cherry-pick the `version.yaml` changes and release notes onto the branch from the PR opened against the main. This will ensure that the release notes are included in the release branch. [Example](https://github.com/radius-project/radius/pull/6114/files). The release branch should now contain all needed patch changes, an updated release version, and patch release notes. 1. Push the commits to the remote and create a pull request targeting the release branch. + ```bash git push origin / ``` -1. Merge the release branch PR into the release branch (this is the branch with the patch changes, updated patch version, and release notes). Then, merge the PR created against `main` into the main branch (this will only contain the updated patch version and the release notes). The release branch changes must be merged before the PR is merged into main since the workflow in the main branch builds the release based on the head of the release branch. If the changes are not merged first to the release branch and then to the main branch, the patch release will not contain the necessary code fixes. +1. Merge the release branch PR into the release branch (this is the branch with the patch changes, updated patch version, and release notes). Then, merge the PR created against `main` into the main branch (this will only contain the updated patch version and the release notes). The release branch changes must be merged before the PR is merged into the main since the workflow in the main branch builds the release based on the head of the release branch. If the changes are not merged first to the release branch and then to the main branch, the patch release will not contain the necessary code fixes. 1. Verify that a patch release was created on Github Releases for the current patch version. [Example](https://github.com/radius-project/radius/releases)