Docs/update release notes #777
Conversation
MiguelMarcelino
force-pushed
the
docs/update-release-notes
branch
from
d3fbd1d
to
b16126c
Compare
![codacy-development[bot]](https://avatars.githubusercontent.com/in/55367?s=60&v=4){kind=small}
| You will now have to generate the release notes for the new self-hosted release. To do so, you will need to first meet all the necessary requirements specified in the [release notes README file](https://github.com/codacy/release-notes-tools/blob/master/README.md#requirements). Please ensure that all the authentication tokens are properly setup before continuing. | ||
| Furthermore, you will also have to ensure that you have GitHub CLI installed. | ||
|
|
||
| After ensuring that you have everything set-up properly, you can now run the makefile target `get_release_notes` to automatically generate the release notes for the new version: |
There was a problem hiding this comment.
We can simplify this step since the instructions you mention are described in the release notes README you link to. It's best to completely defer to that file and have only one source of truth.
| You will now have to generate the release notes for the new self-hosted release. To do so, you will need to first meet all the necessary requirements specified in the [release notes README file](https://github.com/codacy/release-notes-tools/blob/master/README.md#requirements). Please ensure that all the authentication tokens are properly setup before continuing. | |
| Furthermore, you will also have to ensure that you have GitHub CLI installed. | |
| After ensuring that you have everything set-up properly, you can now run the makefile target `get_release_notes` to automatically generate the release notes for the new version: | |
| Make sure that you meet all the requirements specified in the [release notes README file](https://github.com/codacy/release-notes-tools/blob/master/README.md#requirements) and then run the makefile target `get_release_notes` to automatically generate the release notes for the new version: |
There was a problem hiding this comment.
I agree with @nicklem, let's avoid duplicating the requirements here so everything is always centralized and up to date on the codacy/release-notes-tools README.
Also, just to explain why this step didn't provide much more context before, my original idea was that the output of running the Makefile target should guide the Release Manager through fixing any setup issues and point them to the requirements on the README. But I do agree that it makes more sense to leave things explicit here. 👍
|
|
||
| The Release Manager must ensure that we have a stable release candidate and that both the QA team and relevant stakeholders have approved the release. | ||
|
|
||
| Then, the Release Manager releases and announces the new version: | ||
|
|
||
| - [ ] 1. If all is good give a public OK to the release | ||
|
|
||
| - [ ] 2. Tag the CLI and Coverage Reporter with the version of the release being done. | ||
| - [ ] 2. Tag Codacy's [Analysis CLI tool](https://github.com/codacy/codacy-analysis-cli) and [CLI Coverage Reporter](https://github.com/codacy/codacy-coverage-reporter) with the version of the release being done. |
There was a problem hiding this comment.
Tweak to match the official name of the CLI
| - [ ] 2. Tag Codacy's [Analysis CLI tool](https://github.com/codacy/codacy-analysis-cli) and [CLI Coverage Reporter](https://github.com/codacy/codacy-coverage-reporter) with the version of the release being done. | |
| - [ ] 2. Tag the [Codacy Analysis CLI tool](https://github.com/codacy/codacy-analysis-cli) and [CLI Coverage Reporter](https://github.com/codacy/codacy-coverage-reporter) with the version of the release being done. |
There was a problem hiding this comment.
Yes, but even better would be to use the "official" names of both the Codacy Analysis CLI and Codacy Coverage Reporter. 🤓
| - [ ] 2. Tag Codacy's [Analysis CLI tool](https://github.com/codacy/codacy-analysis-cli) and [CLI Coverage Reporter](https://github.com/codacy/codacy-coverage-reporter) with the version of the release being done. | |
| - [ ] 2. Tag the [Codacy Analysis CLI](https://github.com/codacy/codacy-analysis-cli) and [Codacy Coverage Reporter](https://github.com/codacy/codacy-coverage-reporter) CLI tools with the version of the release being done. |
| @@ -258,13 +267,15 @@ Then, the Release Manager releases and announces the new version: | |||
| git checkout x.x.x | |||
| ``` | |||
|
|
|||
| 3. Tag the commit with the current release version prefixed with `self-hosted-`: | |||
| 3. For the CLI Coverage Reporter, you must update the `SELF_HOSTED_CODACY_REPORTER_VERSION` flag on the `get.sh` script found in the project's root. This should reflect the new version that is intended to be used in the new self-hosted release. You do not have to do this for the Analysis CLI tool. | |||
There was a problem hiding this comment.
Tweak for conciseness
| 3. For the CLI Coverage Reporter, you must update the `SELF_HOSTED_CODACY_REPORTER_VERSION` flag on the `get.sh` script found in the project's root. This should reflect the new version that is intended to be used in the new self-hosted release. You do not have to do this for the Analysis CLI tool. | |
| 3. For the CLI Coverage Reporter, you must update the `SELF_HOSTED_CODACY_REPORTER_VERSION` flag on the `get.sh` script found in the project's root. This should match the version used by the new self-hosted release. You do not have to do this for the Analysis CLI tool. |
There was a problem hiding this comment.
As above, let's use the "official" names:
| 3. For the CLI Coverage Reporter, you must update the `SELF_HOSTED_CODACY_REPORTER_VERSION` flag on the `get.sh` script found in the project's root. This should reflect the new version that is intended to be used in the new self-hosted release. You do not have to do this for the Analysis CLI tool. | |
| 3. For the Codacy Coverage Reporter, you must update the `SELF_HOSTED_CODACY_REPORTER_VERSION` flag on the `get.sh` script found in the project's root. This should reflect the new version that is intended to be used in the new self-hosted release. You do not have to do this for the Codacy Analysis CLI. |
|
Thanks @MiguelMarcelino! I left some comments with tweaks, mostly to polish the clarity of the instructions. Looking pretty good already! I suggest waiting for @prcr to return and take a look since he has lots of experience with the process. |
There was a problem hiding this comment.
These are amazing improvements to the Self-hosted release process @MiguelMarcelino! 🙌 I'm already approving because despite @nicklem's and my own suggestions, this new version already includes important details that were missing before.
If you decide to apply some of our feedback and need another approval just let me know.
Also, I'm afraid I took quite some time to realize that this pull request was waiting for my feedback. 😓
| ## 2. Before starting the release | ||
|
|
||
| Before starting the self-hosted release process, the Release Manager should ensure that all the features that should be introduced for this release were successfully deployed and passed all CI workflows. Also, it is recommended to check the Jira tickets to see if there are any red flags that might hinder the release process or cause any delays down the line. | ||
|
|
||
| The Release Manager should also confirm that the changes were properly tested before proceeding with the release. If the Release Manager finds any problems during this process, the Squads involved must be informed to find possible solutions to fix the issues before the release goes forward. | ||
|
|
There was a problem hiding this comment.
It's great that you're giving explicit visibility to all these validations and checks @MiguelMarcelino! 💪 Typically, these go a bit under the radar and as you mention it can cause trouble further down the line.
However, I think these validations should even be performed at an earlier stage, more specifically this is what should be validated when we mention "getting a status from each team" and "confirming if the release can go ahead" on lines #L37-L39 above.
| You will now have to generate the release notes for the new self-hosted release. To do so, you will need to first meet all the necessary requirements specified in the [release notes README file](https://github.com/codacy/release-notes-tools/blob/master/README.md#requirements). Please ensure that all the authentication tokens are properly setup before continuing. | ||
| Furthermore, you will also have to ensure that you have GitHub CLI installed. | ||
|
|
||
| After ensuring that you have everything set-up properly, you can now run the makefile target `get_release_notes` to automatically generate the release notes for the new version: |
There was a problem hiding this comment.
I agree with @nicklem, let's avoid duplicating the requirements here so everything is always centralized and up to date on the codacy/release-notes-tools README.
Also, just to explain why this step didn't provide much more context before, my original idea was that the output of running the Makefile target should guide the Release Manager through fixing any setup issues and point them to the requirements on the README. But I do agree that it makes more sense to leave things explicit here. 👍
| @@ -212,7 +221,7 @@ The Release Manager is also responsible for ensuring that each stakeholder tests | |||
|
|
|||
| ### Approval by the Engineering teams | |||
|
|
|||
| - [ ] 1. Do [exploratory tests](https://handbook.dev.codacy.org/engineering/guidelines/quality/levels.html#exploratory-testing) around the functionality the new features impacted to make sure everything is running as it should, and raise bugs or concerns if any. | |||
| - [ ] 1. Do [exploratory tests](https://codacy.slite.com/app/docs/xonSwt3M2qds8m) around the functionality the new features impacted to make sure everything is running as it should, and raise bugs or concerns if any. | |||
There was a problem hiding this comment.
Here we can link directly to the section about exploratory tests:
| - [ ] 1. Do [exploratory tests](https://codacy.slite.com/app/docs/xonSwt3M2qds8m) around the functionality the new features impacted to make sure everything is running as it should, and raise bugs or concerns if any. | |
| - [ ] 1. Do [exploratory tests](https://codacy.slite.com/app/docs/xonSwt3M2qds8m#a649c63d) around the functionality the new features impacted to make sure everything is running as it should, and raise bugs or concerns if any. |
|
|
||
| The Release Manager must ensure that we have a stable release candidate and that both the QA team and relevant stakeholders have approved the release. | ||
|
|
||
| Then, the Release Manager releases and announces the new version: | ||
|
|
||
| - [ ] 1. If all is good give a public OK to the release | ||
|
|
||
| - [ ] 2. Tag the CLI and Coverage Reporter with the version of the release being done. | ||
| - [ ] 2. Tag Codacy's [Analysis CLI tool](https://github.com/codacy/codacy-analysis-cli) and [CLI Coverage Reporter](https://github.com/codacy/codacy-coverage-reporter) with the version of the release being done. |
There was a problem hiding this comment.
Yes, but even better would be to use the "official" names of both the Codacy Analysis CLI and Codacy Coverage Reporter. 🤓
| - [ ] 2. Tag Codacy's [Analysis CLI tool](https://github.com/codacy/codacy-analysis-cli) and [CLI Coverage Reporter](https://github.com/codacy/codacy-coverage-reporter) with the version of the release being done. | |
| - [ ] 2. Tag the [Codacy Analysis CLI](https://github.com/codacy/codacy-analysis-cli) and [Codacy Coverage Reporter](https://github.com/codacy/codacy-coverage-reporter) CLI tools with the version of the release being done. |
| @@ -258,13 +267,15 @@ Then, the Release Manager releases and announces the new version: | |||
| git checkout x.x.x | |||
| ``` | |||
|
|
|||
| 3. Tag the commit with the current release version prefixed with `self-hosted-`: | |||
| 3. For the CLI Coverage Reporter, you must update the `SELF_HOSTED_CODACY_REPORTER_VERSION` flag on the `get.sh` script found in the project's root. This should reflect the new version that is intended to be used in the new self-hosted release. You do not have to do this for the Analysis CLI tool. | |||
There was a problem hiding this comment.
As above, let's use the "official" names:
| 3. For the CLI Coverage Reporter, you must update the `SELF_HOSTED_CODACY_REPORTER_VERSION` flag on the `get.sh` script found in the project's root. This should reflect the new version that is intended to be used in the new self-hosted release. You do not have to do this for the Analysis CLI tool. | |
| 3. For the Codacy Coverage Reporter, you must update the `SELF_HOSTED_CODACY_REPORTER_VERSION` flag on the `get.sh` script found in the project's root. This should reflect the new version that is intended to be used in the new self-hosted release. You do not have to do this for the Codacy Analysis CLI. |
|
This was just sitting here. Will close for now and reopen if needed. |
I added some extra notes to the release notes that hopefully clarify the release process. Feel free to comment if anything is not according to the remaining docs or if you do not agree.
I updated some links from handbook to Slite, as these were migrated already. Feel free to comment in case I picked the wrong documents or if there are newer ones we should be using.