Skip to content

Commit

Permalink
Update README.md (radius-project#6624)
Browse files Browse the repository at this point in the history 
# Description
Update release doc.

## Type of change
- This pull request is a minor refactor, code cleanup, test improvement,
or other maintenance task and doesn't change the functionality of Radius
(issue link optional).

## Auto-generated summary
<!--
copilot:all
-->
### <samp>🤖 Generated by Copilot at 1bc8d01</samp>

### Summary
:pencil2::memo::heavy_check_mark:

<!--
1. :pencil2: - This emoji represents the correction of typos, spelling,
and grammar errors. For example, line 9 was changed from "This document
describes how to contribute to the releases of the project." to "This
document describes how to contribute to the project's releases."
2. :memo: - This emoji represents the improvement of formatting, style,
and consistency. For example, line 15 was changed from "The project
follows the [Semantic Versioning](https://semver.org/) convention for
its releases." to "The project follows the [Semantic
Versioning](https://semver.org/) (SemVer) convention for its releases."
to introduce the acronym for later use.
3. ✔️ - This emoji represents the clarification and
enhancement of the information and instructions. For example, line 25
was changed from "The project uses [GitHub
milestones](https://docs.github.com/en/github/managing-your-work-on-github/about-milestones)
to track the progress and scope of each release." to "The project uses
[GitHub
milestones](https://docs.github.com/en/github/managing-your-work-on-github/about-milestones)
to track the progress and scope of each release. Each milestone
corresponds to a specific version number and release date." to provide
more details and context.
-->
Fix documentation errors in `contributing-releases` guide. This improves
the readability and accuracy of the guide for contributors and users.

> _We are the ones who fix the docs_
> _We purge the errors from the text_
> _We wield the power of the backticks_
> _We make the releases shine and flex_

### Walkthrough
* Fix typos, grammar, and punctuation errors in
`docs/contributing/contributing-releases/README.md`
([link](https://github.com/radius-project/radius/pull/6624/files?diff=unified&w=0#diff-4b032acb8e706dca3cf78512aadf53ee8b05354e51cd46023ed550c0625b33fbL30-R30),
[link](https://github.com/radius-project/radius/pull/6624/files?diff=unified&w=0#diff-4b032acb8e706dca3cf78512aadf53ee8b05354e51cd46023ed550c0625b33fbL40-R40),
[link](https://github.com/radius-project/radius/pull/6624/files?diff=unified&w=0#diff-4b032acb8e706dca3cf78512aadf53ee8b05354e51cd46023ed550c0625b33fbL63-R55),
[link](https://github.com/radius-project/radius/pull/6624/files?diff=unified&w=0#diff-4b032acb8e706dca3cf78512aadf53ee8b05354e51cd46023ed550c0625b33fbL75-R75),
[link](https://github.com/radius-project/radius/pull/6624/files?diff=unified&w=0#diff-4b032acb8e706dca3cf78512aadf53ee8b05354e51cd46023ed550c0625b33fbL96-R90),
[link](https://github.com/radius-project/radius/pull/6624/files?diff=unified&w=0#diff-4b032acb8e706dca3cf78512aadf53ee8b05354e51cd46023ed550c0625b33fbL105-R97))
* Remove obsolete step of purging CDN cache from release process in
`docs/contributing/contributing-releases/README.md`
([link](https://github.com/radius-project/radius/pull/6624/files?diff=unified&w=0#diff-4b032acb8e706dca3cf78512aadf53ee8b05354e51cd46023ed550c0625b33fbL47-L54))

Signed-off-by: Yetkin Timocin <ytimocin@microsoft.com>
Signed-off-by: ytimocin <ytimocin@microsoft.com>
  • Loading branch information
@ytimocin
ytimocin authored Nov 1, 2023
1 parent 3c6d337 commit a330410
Showing 1 changed file with 18 additions and 23 deletions.
41 changes: 18 additions & 23 deletions docs/contributing/contributing-releases/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand All @@ -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 <COMMIT HASH>
```

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.
Expand All @@ -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 `<major>.<minor>`. Releases will only interact with assets from their channel. For example, the `0.1` `rad` CLI will:
Each release belongs to a *channel* named `<major>.<minor>`. 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 ⚠️ <br>
> ⚠️ 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.<VERSION>
git checkout -b <USERNAME>/<BRANCHNAME>
```

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 <COMMIT HASH>
```

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 `<major>.<minor>` (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 `<major>.<minor>` (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 <USERNAME>/<BRANCHNAME>
```

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)

Expand Down

0 comments on commit a330410

Please sign in to comment.