From d5f87936070a252735ccf6e2709aca7f2f429fd7 Mon Sep 17 00:00:00 2001 From: Julien Palard Date: Fri, 19 Jun 2020 00:05:06 +0200 Subject: [PATCH 1/7] Doing Python Releases 101: Simplified due to centralisation of language switchers in the doc. --- pep-0101.txt | 56 ++++++++++++++-------------------------------------- 1 file changed, 15 insertions(+), 41 deletions(-) diff --git a/pep-0101.txt b/pep-0101.txt index b489e9292b7..643690e770f 100644 --- a/pep-0101.txt +++ b/pep-0101.txt @@ -305,21 +305,16 @@ to perform some manual editing steps. release tag in the repo is signed with your gpg key. When prompted choose the private key you use for signing release tarballs etc. -- For a **new branch** release, ``Doc/tools/static/switchers.js`` - must be updated in all maintained branches, so that the new maintenance - branch is now ``pre`` (for ``pre-release``) and add the new "dev" version. - Also, update ``Doc/tools/templates/indexsidebar.html`` to - increment the version number of the ``in development`` version - and add an entry under it for the new release branch with ``pre-release`` - status. Review the remaining branch entires and consider removing the - oldest ``security-fixes`` branch. - Also, similar changes must be made and committed to these files in all - of the other active branches. Or ask the DE to do this. - -- For a **final** major release, ``Doc/tools/static/switchers.js`` - and ``Doc/tools/templates/indexsidebar.html`` - must be updated in all maintained branches, changing the release branch - from ``pre-release`` to ``stable``. +- For a **new branch** release, add it to `docsbuild script + `_\ + 's ``VERSIONS`` list, so that the new maintenance branch is now + *pre-release* and add the new *in development* version. + +- For a **final** major release, `docsbuild script + `_\ + 's ``VERSIONS`` list must be updated, changing the release branch + from ``pre-release`` to ``stable``, tell the DE to update the + ``/3/`` symlink. - For **begin security-only mode** and **end-of-life** releases, review the two files and update the versions accordingly in all active branches. @@ -454,20 +449,11 @@ to perform some manual editing steps. unpack the HTML docs to ``/srv/docs.python.org/release/X.Y.Z[rcA]`` on docs.nyc1.psf.io. Make sure the files are in group ``docs`` and are group-writeable. If it is a release of a security-fix-only version, - tell the DE to build a version with the "version switcher" - and put it there. + tell the DE to start a build (security-fixes and EOL version are not + built daily). - Let the DE check if the docs are built and work all right. - - If this is a **final** major release: Tell the DE to adapt redirects for - docs.python.org/X.Y in the nginx config for docs.python.org, update - the `docsbuild-scripts `_ - to point to the right stable/development branches, and to install it - and make the initial checkout. - The Doc's ``switchers.js`` script also needs to be - updated. In general, please don't touch things in the toplevel - ``/srv/docs.python.org/`` directory unless you know what you're doing. - - Note both the documentation and downloads are behind a caching CDN. If you change archives after downloading them through the website, you'll need to purge the stale data in the CDN like this:: @@ -895,10 +881,9 @@ else does them. Some of those tasks include: - Optionally making a final release to publish any remaining unreleased changes. -- Check the `docsbuild server script - `_ - to ensure that the docs set for the branch is no longer being built. - If still present, ask the DE to remove this branch from the BRANCHES list. +- Update `docsbuild script + `_\ + 's ``VERSIONS`` list, changing the version state to *EOL*. - On the docs download server (docs.nyc1.psf.io), ensure the top-level symlink points to the upload of unpacked html docs from final release:: @@ -907,17 +892,6 @@ else does them. Some of those tasks include: ls -l 3.3 lrwxrwxrwx 1 nad docs 13 Sep 6 21:38 3.3 -> release/3.3.7 -- In each unretired cpython branch, remove any remaining references to the - retired branch in the Doc version switcher and side bar templates - (file names may vary between branches) [DE]:: - - Doc/tools/static/switchers.js - Doc/tools/templates/indexsidebar.html - - Note that the best way to do this is to make the change in the current - `master` branch, then backport to the other active branches. (This will - hopefully pacify the current state-of-the-art nannybots.) - - Freeze the state of the release branch by creating a tag of its current HEAD and then deleting the branch from the cpython repo. The current HEAD should be at or beyond the final security release for the branch:: From 8b6929746b88366f5fd6d92306eeecdd5afc5929 Mon Sep 17 00:00:00 2001 From: Julien Palard Date: Mon, 22 Jun 2020 17:57:28 +0200 Subject: [PATCH 2/7] backslash not needed. --- pep-0101.txt | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/pep-0101.txt b/pep-0101.txt index 643690e770f..fdb93557ab8 100644 --- a/pep-0101.txt +++ b/pep-0101.txt @@ -306,13 +306,13 @@ to perform some manual editing steps. choose the private key you use for signing release tarballs etc. - For a **new branch** release, add it to `docsbuild script - `_\ - 's ``VERSIONS`` list, so that the new maintenance branch is now + `_'s + ``VERSIONS`` list, so that the new maintenance branch is now *pre-release* and add the new *in development* version. - For a **final** major release, `docsbuild script - `_\ - 's ``VERSIONS`` list must be updated, changing the release branch + `_'s + ``VERSIONS`` list must be updated, changing the release branch from ``pre-release`` to ``stable``, tell the DE to update the ``/3/`` symlink. @@ -882,8 +882,8 @@ else does them. Some of those tasks include: changes. - Update `docsbuild script - `_\ - 's ``VERSIONS`` list, changing the version state to *EOL*. + `_'s + ``VERSIONS`` list, changing the version state to *EOL*. - On the docs download server (docs.nyc1.psf.io), ensure the top-level symlink points to the upload of unpacked html docs from final release:: From d8c05784d1f5c6b50364ddd6957a05e3e5b3e4d0 Mon Sep 17 00:00:00 2001 From: Julien Palard Date: Mon, 22 Jun 2020 17:57:38 +0200 Subject: [PATCH 3/7] FIX: Missing backslash. --- pep-0101.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pep-0101.txt b/pep-0101.txt index fdb93557ab8..7db160ced37 100644 --- a/pep-0101.txt +++ b/pep-0101.txt @@ -386,7 +386,7 @@ to perform some manual editing steps. - The WE has one checkout tree per target architecture, and builds the pcbuild.sln project for the appropriate architecture. - - PC\icons.mak must have been run with nmake. + - PC\\icons.mak must have been run with nmake. - The cmd.exe window in which this is run must have Cygwin/bin in its path (at least for x86). From abf05b2b913af5bd972df8b3399a10d754e5846e Mon Sep 17 00:00:00 2001 From: Julien Palard Date: Mon, 22 Jun 2020 18:05:20 +0200 Subject: [PATCH 4/7] consistency --- pep-0101.txt | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/pep-0101.txt b/pep-0101.txt index 7db160ced37..a984c4c9150 100644 --- a/pep-0101.txt +++ b/pep-0101.txt @@ -308,7 +308,7 @@ to perform some manual editing steps. - For a **new branch** release, add it to `docsbuild script `_'s ``VERSIONS`` list, so that the new maintenance branch is now - *pre-release* and add the new *in development* version. + ``pre-release`` and add the new ``in development`` version. - For a **final** major release, `docsbuild script `_'s @@ -449,8 +449,8 @@ to perform some manual editing steps. unpack the HTML docs to ``/srv/docs.python.org/release/X.Y.Z[rcA]`` on docs.nyc1.psf.io. Make sure the files are in group ``docs`` and are group-writeable. If it is a release of a security-fix-only version, - tell the DE to start a build (security-fixes and EOL version are not - built daily). + tell the DE to start a build (``security-fixes`` and ``EOL`` version + are not built daily). - Let the DE check if the docs are built and work all right. @@ -883,7 +883,7 @@ else does them. Some of those tasks include: - Update `docsbuild script `_'s - ``VERSIONS`` list, changing the version state to *EOL*. + ``VERSIONS`` list, changing the version state to ``EOL``. - On the docs download server (docs.nyc1.psf.io), ensure the top-level symlink points to the upload of unpacked html docs from final release:: From ad4cd7a9cf5823a17501ec6739c91c23bc27c14a Mon Sep 17 00:00:00 2001 From: Julien Palard Date: Mon, 22 Jun 2020 18:15:49 +0200 Subject: [PATCH 5/7] Factor 3 links. --- pep-0101.txt | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/pep-0101.txt b/pep-0101.txt index a984c4c9150..4386f8768a8 100644 --- a/pep-0101.txt +++ b/pep-0101.txt @@ -305,16 +305,14 @@ to perform some manual editing steps. release tag in the repo is signed with your gpg key. When prompted choose the private key you use for signing release tarballs etc. -- For a **new branch** release, add it to `docsbuild script - `_'s +- For a **new branch** release, add it to `docsbuild scripts`_' ``VERSIONS`` list, so that the new maintenance branch is now ``pre-release`` and add the new ``in development`` version. -- For a **final** major release, `docsbuild script - `_'s - ``VERSIONS`` list must be updated, changing the release branch - from ``pre-release`` to ``stable``, tell the DE to update the - ``/3/`` symlink. +- For a **final** major release, `docsbuild scripts`_' ``VERSIONS`` + list must be updated, changing the release branch from + ``pre-release`` to ``stable``, tell the DE to update the ``/3/`` + symlink. - For **begin security-only mode** and **end-of-life** releases, review the two files and update the versions accordingly in all active branches. @@ -881,9 +879,8 @@ else does them. Some of those tasks include: - Optionally making a final release to publish any remaining unreleased changes. -- Update `docsbuild script - `_'s - ``VERSIONS`` list, changing the version state to ``EOL``. +- Update `docsbuild scripts`_' ``VERSIONS`` list, changing the + version state to ``EOL``. - On the docs download server (docs.nyc1.psf.io), ensure the top-level symlink points to the upload of unpacked html docs from final release:: @@ -993,6 +990,9 @@ Copyright This document has been placed in the public domain. +.. _docsbuild scripts: + https://github.com/python/docsbuild-scripts/blob/master/build_docs.py + .. Local Variables: mode: indented-text From 82ae4b22bc09c3977997296fbc8a922241bb2afe Mon Sep 17 00:00:00 2001 From: Julien Palard Date: Mon, 22 Jun 2020 22:36:18 +0200 Subject: [PATCH 6/7] FIX: Ugly apostrophes after [1]. --- pep-0101.txt | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/pep-0101.txt b/pep-0101.txt index 4386f8768a8..56b19bc0adb 100644 --- a/pep-0101.txt +++ b/pep-0101.txt @@ -305,12 +305,12 @@ to perform some manual editing steps. release tag in the repo is signed with your gpg key. When prompted choose the private key you use for signing release tarballs etc. -- For a **new branch** release, add it to `docsbuild scripts`_' - ``VERSIONS`` list, so that the new maintenance branch is now +- For a **new branch** release, add it to the ``VERSIONS`` list of + `docsbuild scripts`_, so that the new maintenance branch is now ``pre-release`` and add the new ``in development`` version. -- For a **final** major release, `docsbuild scripts`_' ``VERSIONS`` - list must be updated, changing the release branch from +- For a **final** major release, update the ``VERSIONS`` list of + `docsbuild scripts`_: the release branch must be changed from ``pre-release`` to ``stable``, tell the DE to update the ``/3/`` symlink. @@ -879,7 +879,7 @@ else does them. Some of those tasks include: - Optionally making a final release to publish any remaining unreleased changes. -- Update `docsbuild scripts`_' ``VERSIONS`` list, changing the +- Update the ``VERSIONS`` list of `docsbuild scripts`_: change the version state to ``EOL``. - On the docs download server (docs.nyc1.psf.io), ensure the top-level From 24784f9fdb7c0c8e99ddf6fa1c6c32b0d72413d7 Mon Sep 17 00:00:00 2001 From: Julien Palard Date: Sat, 7 Nov 2020 11:31:07 +0100 Subject: [PATCH 7/7] Missing --- pep-0101.txt | 3 +++ 1 file changed, 3 insertions(+) diff --git a/pep-0101.txt b/pep-0101.txt index 56b19bc0adb..c34c59a2218 100644 --- a/pep-0101.txt +++ b/pep-0101.txt @@ -452,6 +452,9 @@ to perform some manual editing steps. - Let the DE check if the docs are built and work all right. + - If this is a **final** major release: Tell the DE to adapt redirects for + docs.python.org/X.Y in the nginx config for docs.python.org. + - Note both the documentation and downloads are behind a caching CDN. If you change archives after downloading them through the website, you'll need to purge the stale data in the CDN like this::