diff --git a/source/_images/drafting-new-release.png b/source/_images/drafting-new-release.png new file mode 100644 index 0000000..ee15a6d Binary files /dev/null and b/source/_images/drafting-new-release.png differ diff --git a/source/_images/prepare-release-workflow.png b/source/_images/prepare-release-workflow.png new file mode 100644 index 0000000..0e69b6c Binary files /dev/null and b/source/_images/prepare-release-workflow.png differ diff --git a/source/_images/publish-release-job.png b/source/_images/publish-release-job.png new file mode 100644 index 0000000..e684592 Binary files /dev/null and b/source/_images/publish-release-job.png differ diff --git a/source/_images/publish-release-workflow-list.png b/source/_images/publish-release-workflow-list.png new file mode 100644 index 0000000..d483186 Binary files /dev/null and b/source/_images/publish-release-workflow-list.png differ diff --git a/source/_images/release-helper-changelog-contributor-list-standalone.png b/source/_images/release-helper-changelog-contributor-list-standalone.png new file mode 100644 index 0000000..8565918 Binary files /dev/null and b/source/_images/release-helper-changelog-contributor-list-standalone.png differ diff --git a/source/_images/release-helper-changelog-contributor-list.png b/source/_images/release-helper-changelog-contributor-list.png new file mode 100644 index 0000000..7d61d38 Binary files /dev/null and b/source/_images/release-helper-changelog-contributor-list.png differ diff --git a/source/_images/release-helper-changelog-milestone.png b/source/_images/release-helper-changelog-milestone.png new file mode 100644 index 0000000..91196aa Binary files /dev/null and b/source/_images/release-helper-changelog-milestone.png differ diff --git a/source/_images/release-helper-changelog-unreleased.png b/source/_images/release-helper-changelog-unreleased.png new file mode 100644 index 0000000..1ad50fa Binary files /dev/null and b/source/_images/release-helper-changelog-unreleased.png differ diff --git a/source/core-devs/index.rst b/source/core-devs/index.rst new file mode 100644 index 0000000..7410085 --- /dev/null +++ b/source/core-devs/index.rst @@ -0,0 +1,9 @@ +Core Developer's reference +========================== + +Resources that are of most use to Core Developers. + +.. toctree:: + :maxdepth: 2 + + release-process diff --git a/source/core-devs/release-process.rst b/source/core-devs/release-process.rst new file mode 100644 index 0000000..34f1a05 --- /dev/null +++ b/source/core-devs/release-process.rst @@ -0,0 +1,326 @@ +Release process +=============== + +Red's release process involves a bit of work. This document attempts to collect, +in one place, all the steps needed to make a release of Red. + +Types of releases +----------------- + +- Breaking release (``3.x+1.0``) + + Release with breaking changes, done from ``V3/develop``. + +- Standard release (``3.x.y+1``) + + Release without breaking changes that may contain both features and bugfixes. + + This is done from ``V3/develop`` or ``3.x`` branch + if a breaking release is currently in development. + +- Maintenance release (``3.x.y+1``) + + Release without breaking changes that only contains cherry-picked enhancements and bugfixes. + + Quite similar to a standard release but it is done from a short-lived release branch + using the tag of a previous version as a base. + +- Hotfix release (``3.x.y+1``) + + Release that is meant to quickly patch one of the currently supported releases + (usually it is just the latest). + + This is done from a short-lived release branch using the tag of a previous version as a base, + or from ``V3/develop``/``3.x`` if it doesn't contain any meaningful code changes yet. + + +Making a release +---------------- + +As much as possible, the release steps are automated and guided by the **Release Helper** script, +which is shipped with the repository at ``tools/release_helper.py``. + +To use the script, you will need to install the `GitHub CLI `__ +and authenticate with your GitHub account using the ``gh auth login`` command. + +The script can be started simply by running: + +.. prompt:: + + .venv/bin/python tools/release_helper.py + +which will ask you about the release type you want to make and then guide you through the process. + +#. Ensure there are no release blockers. + + .. note:: + + These will be listed to you by the **Release Helper**. + + .. tab:: Hotfix release + + You can *generally* skip this. Might still be worth checking + in case there is some blocker related to release workflow that could potentially affect you. + + .. tab:: Everything else + + Look at the milestone for the next release and check if there are any Release Blockers + (labelled as "Release Blocker" on the issue tracker) that need to be handled before the release. + +#. Check state of all open pull requests for this milestone. + + .. note:: + + These will be listed to you by the **Release Helper**. + + .. tab:: Hotfix release + + This is a hotfix release, you should focus on getting the critical fix out, + the other PRs should not be important. However, you should still update the milestone + to make your and others' job easier later. + + .. tab:: Everything else + + Decide which should be kept for the release, cooperate with another org member(s) on this. + Move any pull requests not targeted for release to a new milestone with name of the release + that should come after current one. + +#. Review changelog PR. + + .. note:: + + At this point, you should have an up-to-date milestone containing all PRs + that are contained in this release. If you're not sure if all PRs are properly assigned, + you might find **Release Helper**'s ``unreleased`` command (or its + "Show unreleased commits without a milestone" counter-part from the guided flow) helpful: + + .. figure:: /_images/release-helper-changelog-unreleased.png + :target: /_images/release-helper-changelog-unreleased.png + + The changelog PR should always be merged into ``V3/develop``. You should remember to later + cherry-pick/backport it to a proper branch if you're not making a release from ``V3/develop``. + + .. tab:: Hotfix release + + Hotfix releases need to contain a changelog. + + It can be limited to a short description of what the hotfix release fixes, for example see: + `Red 3.4.12 changelog `__ + + .. tab:: Everything else + + - Add (or ask PR author to add) any missing entries based on the release's milestone. + + You might find the **Release Helper**'s ``milestone`` command helpful here: + + .. figure:: /_images/release-helper-changelog-milestone.png + :target: /_images/release-helper-changelog-milestone.png + + - Update the contributors list in the changelog using contributors list for the milestone + that you can generate using **Release Helper**'s ``contributors`` command (or its + "Get contributor list formatted for the changelog" counter-part from the guided flow): + + .. figure:: /_images/release-helper-changelog-contributor-list-standalone.png + :target: /_images/release-helper-changelog-contributor-list-standalone.png + + .. figure:: /_images/release-helper-changelog-contributor-list.png + :target: /_images/release-helper-changelog-contributor-list.png + + - Merge the PR once it's ready. + +#. Run "Prepare Release" workflow. + + .. note:: + + This can be triggered automatically with the **Release Helper**. + The below steps are an alternative way that doesn't require the use of that tool. + + Go to https://github.com/Cog-Creators/Red-DiscordBot/actions/workflows/prepare_release.yml + + .. tip:: + + This step only takes care of automatically creating some PRs, + it won't release anything, don't worry! + + - Click on the "Run workflow" button + - Choose the long-lived branch for the version you're releasing + + This is either ``V3/develop`` or ``3.x`` branch that you will be cherry-picking changes from, + not the short-lived release branch. + + - Click on the "Run workflow" button in the popover + + .. figure:: /_images/prepare-release-workflow.png + :target: /_images/prepare-release-workflow.png + +#. Merge the automatically created PRs. + + .. note:: + + These will be listed to you by the **Release Helper**. + + Wait for "Prepare Release" workflow to finish and merge the PRs that it created. + +#. Create a short-lived release branch. + + .. note:: + + This is a manual step - the **Release Helper** will pause at this step + for you to perform the necessary actions. + + .. tab:: Hotfix release + + .. note:: + + This does not apply if you're releasing from the long-lived branch + (i.e. ``V3/develop`` or ``3.x``). + + - Create a branch named ``V3/release/VERSION_TO_RELEASE_HERE`` based off + a tag of previous version. + + This can be done with the command: + + .. prompt:: + + git checkout -b V3/release/VERSION_TO_RELEASE_HERE PREVIOUS_VERSION + + - Cherry-pick the critical fix, the changelog, the automated PRs, and the version bump. + - Push the branch to upstream repository (Cog-Creators/Red-DiscordBot) + + With a typical setup where ``upstream`` remote points to upstream repository + and ``origin`` points to user's fork, this can be done with the command: + + .. prompt:: + + git push -u upstream V3/release/VERSION_TO_RELEASE_HERE + + .. tab:: Maintenance release + + - Create a branch named ``V3/release/VERSION_TO_RELEASE_HERE`` based off + a tag of previous version. + + This can be done with the command: + + .. prompt:: + + git checkout -b V3/release/VERSION_TO_RELEASE_HERE PREVIOUS_VERSION + + - Cherry-pick the relevant changes, the changelog, the automated PRs, and the version bump. + - Push the branch to upstream repository (Cog-Creators/Red-DiscordBot) + + With a typical setup where ``upstream`` remote points to upstream repository + and ``origin`` points to user's fork, this can be done with the command: + + .. prompt:: + + git push -u upstream V3/release/VERSION_TO_RELEASE_HERE + + .. tab:: Breaking or standard release + + This does not apply. + + .. _write-announcement: + +#. Write (not send!) an announcement for the new release. + + .. note:: + + This and the following steps are not performed by the **Release Helper**. + + This is the announcement that you will later `post to Discord `. + + Remember to: + + - Mention that the changelog contains "Read before updating" section (if applicable): + + .. code:: markdown + + __**Before you update**: please ensure that you read the “Read before updating” section in the changelogs first.__ + + - Include the link to changelog. + + .. note:: + + - Use link to ``stable`` or tagged (i.e. ``3.4.0``) version of docs, + DO NOT USE link to ``latest``. + - The changelog link should point to the section for the specific release + (the part after ``#`` in the URL) + + For example: + + .. code:: markdown + + Full changelogs here: + +#. Make a new release through `GitHub Releases `__. + + .. attention:: + + Remember to change the target branch when you're not releasing from ``V3/develop``! + + - Put the version number as tag name (i.e. ``3.4.0``) + - Put the version number prepended with "v" as release title (i.e. ``v3.4.0``) + - Ensure that the target branch is selected correctly + - Write a short release description + + The description can be informal, the changelog has all the important information already. + Be sure to put a link to full changelog from our docs in release description. + + The changelog link should point to the section for the specific release + (the part after ``#`` in the URL), e.g.: + + .. code:: markdown + + Full changelog: https://docs.discord.red/en/latest/changelog_3_4_0.html#redbot-3-4-12-2021-06-17 + + .. figure:: /_images/drafting-new-release.png + :target: /_images/drafting-new-release.png + +#. Check the correctness of Release information and approve or reject the environment run. + + .. danger:: + + This is the step when the new version will get published. + + At this point you should already have `written the announcement ` + that you will be sending after this is done. + + Go to https://github.com/Cog-Creators/Red-DiscordBot/actions/workflows/publish_release.yml + + - Click on the first workflow run (with a clock icon) on the list. + + .. figure:: /_images/publish-release-workflow-list.png + :target: /_images/publish-release-workflow-list.png + + - Click on the "GO HERE BEFORE APPROVING" job. + - Expand the "REVIEW OUTPUT OF THIS STEP BEFORE APPROVING" step. + - **Verify the release information printed in the step is correct.** + + .. figure:: /_images/publish-release-job.png + :target: /_images/publish-release-job.png + + - Go back to Summary, click on "Review deployments" and approve or reject the environment run. + +#. Wait for the CI to finish its job. + + "Publish Release" workflow needs to finish before you can continue. + You should also wait for the ``stable`` build on the Read The Docs to finish if it hasn't already. + + .. _publish-announcement: + +#. Send and publish an announcement in Discord. + + This is the announcement that you wrote in `the earlier step `. + +#. Merge the PR bumping to dev version. + + It should have been automatically created during "Publish release" workflow + that you approved earlier. + +#. Close release milestone and create a new one. + + Close the milestone for the release that was just made + and create an appropriately named milestone for the next release. + +After all this is done, you can enjoy the new release +(or make a hotfix if there's a critical issue, let's hope there's not though :)) diff --git a/source/index.rst b/source/index.rst index 759f538..22f1277 100644 --- a/source/index.rst +++ b/source/index.rst @@ -8,4 +8,6 @@ Full Table of Contents ---------------------- .. toctree:: - :maxdepth: 2 + :maxdepth: 3 + + core-devs/index