From df0d1a08d58ccfd2deec55b9171dfeaa8fb30cfd Mon Sep 17 00:00:00 2001 From: Sviatoslav Sydorenko Date: Thu, 11 Apr 2024 01:14:10 +0200 Subject: [PATCH] =?UTF-8?q?=F0=9F=93=9D=20Publish=20a=20release=20guide=20?= =?UTF-8?q?document?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/changelog-fragments.d/README.rst | 2 - docs/conf.py | 7 +++ docs/contributing/release_guide.rst | 83 +++++++++++++++++++++++++++ docs/index.rst | 5 ++ 4 files changed, 95 insertions(+), 2 deletions(-) create mode 100644 docs/contributing/release_guide.rst diff --git a/docs/changelog-fragments.d/README.rst b/docs/changelog-fragments.d/README.rst index a6e1a254c5..78a1184247 100644 --- a/docs/changelog-fragments.d/README.rst +++ b/docs/changelog-fragments.d/README.rst @@ -1,5 +1,3 @@ -.. _Adding change notes with your PRs: - Adding change notes with your PRs ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/docs/conf.py b/docs/conf.py index a5103f5cd8..adc5dba0f4 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -29,6 +29,7 @@ extensions = [ 'sphinx.ext.autodoc', + 'sphinx.ext.autosectionlabel', # autocreate section targets for refs 'sphinx.ext.doctest', 'sphinx.ext.extlinks', 'sphinx.ext.intersphinx', @@ -130,6 +131,12 @@ ] linkcheck_workers = 25 +# -- Options for sphinx.ext.autosectionlabel extension ----------------------- + +# Ref: +# https://www.sphinx-doc.org/en/master/usage/extensions/autosectionlabel.html +autosectionlabel_maxdepth = 2 # mitigate Towncrier nested subtitles collision + nitpicky = True # NOTE: consider having a separate ignore file diff --git a/docs/contributing/release_guide.rst b/docs/contributing/release_guide.rst new file mode 100644 index 0000000000..df53740461 --- /dev/null +++ b/docs/contributing/release_guide.rst @@ -0,0 +1,83 @@ +************* +Release Guide +************* + +Welcome to the |project| Release Guide! + +This page contains information on how to release a new version +of |project| using the automated Continuous Delivery pipeline. + +.. tip:: + + The intended audience for this document is maintainers + and core contributors. + + +Pre-release activities +====================== + +1. Check if there are any open Pull Requests that could be + desired in the upcoming release. If there are any — merge + them. If some are incomplete, try to get them ready. + Don't forget to review the enclosed change notes per our + guidelines. +2. Visually inspect the draft section of the :ref:`Change log` + page. Make sure the content looks consistent, uses the same + writing style, targets the end-users and adheres to our + documented guidelines. + Most of the changelog sections will typically use the past + tense or another way to relay the effect of the changes for + the users, since the previous release. + It should not target core contributors as the information + they are normally interested in is already present in the + Git history. + Update the changelog fragments if you see any problems with + this changelog section. +3. If you are satisfied with the above, inspect the changelog + section categories in the draft. Presence of the breaking + changes or features will hint you what version number + segment to bump for the release. + +.. seealso:: + + :ref:`Adding change notes with your PRs` + Writing beautiful changelogs for humans + + +The release stage +================= + +1. Open the `GitHub Actions CI/CD workflow page `_ in your web browser. +2. Click the gray button :guilabel:`Run workflow` in the blue + banner at the top of the workflow runs list. +3. In the form that appears, enter the version you used in the + preparation steps, into the mandatory field. Do not prepend + a leading-``v``. Just use the raw version number as per + :pep:`440`. +4. Now, click the green button :guilabel:`Run workflow`. +5. At some point, the workflow gets to the job for publishing + to the "production" PyPI and stops there. You will see a + banner informing you that a deployment approval is needed. + You will also get an email notification with the same + information and a link to the deployment approval view. +6. While the normal PyPI upload hasn't happened yet, the + TestPyPI one proceeds. This gives you a chance to optionally + verify what got published there and decide if you want to + abort the process. +7. Approve the deployment and wait for the workflow to complete. +8. Verify that the following things got created: + + - a PyPI release + - a Git tag + - a GitHub Releases page + - a GitHub Discussions page + - a release pull request on GitHub + +9. Merge that pull request using the natural ``git merge`` strategy + avoiding squash or rebase. +10. Tell everyone you released a new version of |project| :) + + +.. _GitHub Actions CI/CD workflow: + https://github.com/cherrypy/cheroot/actions/workflows/ci-cd.yml diff --git a/docs/index.rst b/docs/index.rst index e90883d0e2..bf39dcf8ab 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -14,6 +14,11 @@ Welcome to Cheroot documentation! contributing/guidelines +.. toctree:: + :caption: Maintenance + + contributing/release_guide + .. toctree:: :caption: Reference