From 58c3e8c512a8ed81b55623fe17e18a57bce9d359 Mon Sep 17 00:00:00 2001 From: Manuel Kaufmann Date: Tue, 25 Oct 2022 19:01:27 +0200 Subject: [PATCH 1/5] Update guide to upgrade the Python version - add step for GitHub Action - add step for Read the Docs --- .overrides/upgrade-python-version.rst | 14 +++++++++++--- 1 file changed, 11 insertions(+), 3 deletions(-) diff --git a/.overrides/upgrade-python-version.rst b/.overrides/upgrade-python-version.rst index 89388f330b..0168e7c4b4 100644 --- a/.overrides/upgrade-python-version.rst +++ b/.overrides/upgrade-python-version.rst @@ -53,7 +53,7 @@ We are currently in branch 3.10, and we want to update the strings from 3.11. pip install -r requirements.txt -#. Create the .po files from the new source code. This will generate all the .po files for version 3.8:: +#. Create the .po files from the new source code. This will generate all the .po files for version 3.11:: SPHINX_GETTEXT=True sphinx-build -j auto -b gettext -d _build/doctrees . ../python-docs-es-pot @@ -69,8 +69,8 @@ We are currently in branch 3.10, and we want to update the strings from 3.11. #. At this point, all the `.po` files will have a different comment on each translation phrase, for example:: - -#: ../Doc/whatsnew/3.9.rst:3 - +#: ../python-docs-es/cpython/Doc/whatsnew/3.9.rst:3 + -#: ../Doc/whatsnew/3.11.rst:3 + +#: ../python-docs-es/cpython/Doc/whatsnew/3.11.rst:3 As you can see, it added the path of the local repository, but you can remove it from it with this regular expression:: @@ -91,3 +91,11 @@ We are currently in branch 3.10, and we want to update the strings from 3.11. you will find many warnings that needs to be fixed before the push of the new branch is done. So prepare a cup of any hot beverage and fix them. + + +Once the process is completely and you are happy with the results, +there are a few extra steps to finish the process:: + +#. Upgrade GitHub Actions to use Python 3.11 + +#. Update Read the Docs project to use 3.11 in the build and also as default branch/version From 85afe7c557ad6959039f693bd0dd4d5dd664e745 Mon Sep 17 00:00:00 2001 From: Manuel Kaufmann Date: Tue, 25 Oct 2022 20:04:32 +0200 Subject: [PATCH 2/5] Updates while doing the stream with Cristian and Marcos --- .overrides/upgrade-python-version.rst | 63 ++++++++++++++++++--------- 1 file changed, 43 insertions(+), 20 deletions(-) diff --git a/.overrides/upgrade-python-version.rst b/.overrides/upgrade-python-version.rst index 0168e7c4b4..62f06a7dd7 100644 --- a/.overrides/upgrade-python-version.rst +++ b/.overrides/upgrade-python-version.rst @@ -8,43 +8,59 @@ We are currently in branch 3.10, and we want to update the strings from 3.11. #. Make sure you are in a clean state of the branch 3.10 -#. Create a new branch +#. Create a new branch called ``3.11`` -#. Fetch the `latest commit of 3.10 branch `_:: +#. Initialize the submodules:: + + git submodule init + git submodule update + +#. Fetch the `latest commit of 3.11 branch `_:: cd cpython/ - git fetch --depth 1 origin 69b6b56d857440183e227ca0b10c84bca4239985 + git fetch --depth 1 origin b3cafb60afeb2300002af9982d43703435b8302d .. note:: you could also base the hash on the 'git tag' from the desired - version: `git checkout tags/v3.11.0 -b 3.11` considering that - `3.11` doesn't exist locally. + version: ``git checkout tags/v3.11.0 -b 3.11`` considering that + ``3.11`` doesn't exist locally. #. Checkout that commit locally:: git checkout 69b6b56d857440183e227ca0b10c84bca4239985 -#. Update the branch on the `Makefile` and check the `requirements.txt` from +#. Update the branch on the ``Makefile`` and check the ``requirements.txt`` from the cpython repository, to see if upgrades on the modules like sphinx is needed. -#. Verify that the docs build with the new versions you changed from - `requirements.txt` mainly the sphinx version. - #. Commit the update of the submodule change:: git add cpython git commit -m "Update the cpython submodule" - .. note:: This is important, so the later `make build` step will not reset + .. note:: This is important, so the later ``make build`` step will not reset the cpython submodule to the previous hash on the old branch. +#. Verify that the docs build with the new versions you changed from + ``requirements.txt`` mainly the sphinx version:: + + make html + + .. note:: + + It may fail the build because there may be files + that don't exist anymore in the new branch. + If that's the case, just continue with the steps + and verify the build later. + #. Clean possible garbage (form previous builds):: rm -rf _build ../python-docs-es-pot cpython/Doc/CONTRIBUTING.rst cpython/Doc/upgrade-python-version.rst - .. note: the 'python-docs-es-pot' is a temporary directory that is created - in the next step. It's included here because it might be a leftover - from previous attempts on your machine. + .. note:: + + The 'python-docs-es-pot' is a temporary directory that is created + in the next step. It's included here because it might be a leftover + from previous attempts on your machine. #. Create a virtual environment and install the dependencies of the project:: @@ -59,31 +75,38 @@ We are currently in branch 3.10, and we want to update the strings from 3.11. .. note:: - In `../python-docs-es-pot` directory, we will have the new .pot files with new strings from 3.11 branch. + In ``../python-docs-es-pot`` directory, we will have the new .pot files with new strings from 3.11 branch. All these strings will be *untranslated* at this point. #. Now, we update our translated files form the source language (English) with new strings:: sphinx-intl update --language es --pot-dir ../python-docs-es-pot --locale-dir cpython/locales/ -#. At this point, all the `.po` files will have a different comment on each translation phrase, +#. At this point, all the ``.po`` files will have a different comment on each translation phrase, for example:: - -#: ../Doc/whatsnew/3.11.rst:3 - +#: ../python-docs-es/cpython/Doc/whatsnew/3.11.rst:3 + -#: ../python-docs-es/cpython/Doc/whatsnew/3.11.rst:3 + +#: ../Doc/whatsnew/3.11.rst:3 As you can see, it added the path of the local repository, but you can remove it from it with this regular expression:: sed -i **/*.po -e "s|python-docs-es/cpython/||g" - ..note:: if you have your local repository cloned with a different name, - please make sure to adapt the expression. + .. note:: + + If you have your local repository cloned with a different name, + please make sure to adapt the expression. -#. Pass `powrap` to make the column widths consistent:: +#. Pass ``powrap`` to make the column widths consistent:: powrap --modified + .. note:: + + Make sure you have installed ``gettext``, + since it's required for the previous command. + #. Prepare for fireworks! Now it's time for an initial build:: make build From 6a5ce41ca394aa54d438ba3f09e7965f4ff5ca1e Mon Sep 17 00:00:00 2001 From: Manuel Kaufmann Date: Tue, 25 Oct 2022 20:11:46 +0200 Subject: [PATCH 3/5] New hash for commit --- .overrides/upgrade-python-version.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.overrides/upgrade-python-version.rst b/.overrides/upgrade-python-version.rst index 62f06a7dd7..23e5a84449 100644 --- a/.overrides/upgrade-python-version.rst +++ b/.overrides/upgrade-python-version.rst @@ -15,7 +15,7 @@ We are currently in branch 3.10, and we want to update the strings from 3.11. git submodule init git submodule update -#. Fetch the `latest commit of 3.11 branch `_:: +#. Fetch the `latest commit of 3.11 branch `_:: cd cpython/ git fetch --depth 1 origin b3cafb60afeb2300002af9982d43703435b8302d From 1ee6b27a36a1a6d251e23c2cd5fee30519cf6c56 Mon Sep 17 00:00:00 2001 From: Manuel Kaufmann Date: Tue, 25 Oct 2022 20:31:16 +0200 Subject: [PATCH 4/5] Update commit --- .overrides/upgrade-python-version.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.overrides/upgrade-python-version.rst b/.overrides/upgrade-python-version.rst index 23e5a84449..aef9fdcfba 100644 --- a/.overrides/upgrade-python-version.rst +++ b/.overrides/upgrade-python-version.rst @@ -26,7 +26,7 @@ We are currently in branch 3.10, and we want to update the strings from 3.11. #. Checkout that commit locally:: - git checkout 69b6b56d857440183e227ca0b10c84bca4239985 + git checkout b3cafb60afeb2300002af9982d43703435b8302d #. Update the branch on the ``Makefile`` and check the ``requirements.txt`` from the cpython repository, to see if upgrades on the modules like sphinx is From 918c13d5af8a86f3e1849bf26b16aee8efb14b1a Mon Sep 17 00:00:00 2001 From: Manuel Kaufmann Date: Tue, 25 Oct 2022 20:31:36 +0200 Subject: [PATCH 5/5] Exclude some files that are not required --- .gitignore | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/.gitignore b/.gitignore index 9f5d8655de..e740f19cc5 100644 --- a/.gitignore +++ b/.gitignore @@ -75,3 +75,9 @@ coverage.xml # OSX .DS_Store + +.potodo/ +git_diff.po +CONTRIBUTING.po +reviewers-guide.po +upgrade-python-version.po \ No newline at end of file