DOC: Update the RELEASE_WALKTHROUGH.rst file.

[skip cirrus] [skip azp] [skip actions]

Author: charris

doc/RELEASE_WALKTHROUGH.rst

@@ -1,7 +1,7 @@
-This is a walkthrough of the NumPy 1.21.0 release on Linux, modified for
+This is a walkthrough of the NumPy 2.1.0 release on Linux, modified for
 building with GitHub Actions and cibuildwheels and uploading to the
 `anaconda.org staging repository for NumPy <https://anaconda.org/multibuild-wheels-staging/numpy>`_.
-The commands can be copied into the command line, but be sure to replace 1.21.0
+The commands can be copied into the command line, but be sure to replace 2.1.0
 by the correct version. This should be read together with the
 :ref:`general release guide <prepare_release>`.
 
@@ -44,42 +44,62 @@ Backport pull requests
 ----------------------
 
 Changes that have been marked for this release must be backported to the
-maintenance/1.21.x branch.
+maintenance/2.1.x branch.
+
+Update 2.1.0 milestones
+-----------------------
+
+Look at the issues/prs with 2.1.0 milestones and either push them off to a
+later version, or maybe remove the milestone.
 
 
 Make a release PR
 =================
 
-Five documents usually need to be updated or created for the release PR:
+Four documents usually need to be updated or created for the release PR:
 
 - The changelog
 - The release-notes
 - The ``.mailmap`` file
 - The ``pyproject.toml`` file
-- The ``pyproject.toml.setuppy`` file # 1.26.x only
 
 These changes should be made in an ordinary PR against the maintenance branch.
-The commit message should contain a ``[wheel build]`` directive to test if the
+The commit heading should contain a ``[wheel build]`` directive to test if the
 wheels build. Other small, miscellaneous fixes may be part of this PR. The
 commit message might be something like::
 
-    REL: Prepare for the NumPy 1.20.0 release
+    REL: Prepare for the NumPy 2.1.0 release [wheel build]
 
-    - Create 1.20.0-changelog.rst.
-    - Update 1.20.0-notes.rst.
+    - Create 2.1.0-changelog.rst.
+    - Update 2.1.0-notes.rst.
     - Update .mailmap.
     - Update pyproject.toml
-    - Update pyproject.toml.setuppy
 
-    [wheel build]
+
+Set the release version
+-----------------------
+
+Check the ``pyproject.toml`` file and set the release version if needed::
+
+    $ gvim pyproject.toml
+
+
+Check the ``pavement.py`` and ``doc/source/release.rst`` files
+--------------------------------------------------------------
+
+Check that the ``pavement.py`` file points to the correct release notes. It should
+have been updated after the last release, but if not, fix it now. Also make
+sure that the notes have an entry in the ``release.rst`` file::
+
+    $ gvim pavement.py doc/source/release.rst
 
 
 Generate the changelog
 ----------------------
 
 The changelog is generated using the changelog tool::
 
-    $ spin changelog $GITHUB v1.20.0..maintenance/1.21.x > doc/changelog/1.21.0-changelog.rst
+    $ spin changelog $GITHUB v2.0.0..maintenance/2.1.x > doc/changelog/2.1.0-changelog.rst
 
 where ``GITHUB`` contains your GitHub access token. The text will need to be
 checked for non-standard contributor names and dependabot entries removed. It
@@ -95,36 +115,20 @@ Finish the release notes
 ------------------------
 
 If there are any release notes snippets in ``doc/release/upcoming_changes/``,
-run ``spin docs`` to build the docs, incorporate the contents of the generated
-``doc/source/release/notes-towncrier.rst`` file into the release notes file
-(e.g., ``doc/source/release/2.3.4-notes.rst``), and delete the now-processed
-snippets in ``doc/release/upcoming_changes/``. This is safe to do multiple
-times during a release cycle.
-
-The generated release note will always need some fixups, the introduction will
-need to be written, and significant changes should be called out. For patch
-releases the changelog text may also be appended, but not for the initial
-release as it is too long. Check previous release notes to see how this is
-done.
-
-
-Set the release version
------------------------
-
-Check the ``pyproject.toml`` and ``pyproject.toml.setuppy`` files and set the
-release version if needed::
-
-    $ gvim pyproject.toml pyproject.toml.setuppy
-
-
-Check the ``pavement.py`` and ``doc/source/release.rst`` files
---------------------------------------------------------------
-
-Check that the ``pavement.py`` file points to the correct release notes. It should
-have been updated after the last release, but if not, fix it now. Also make
-sure that the notes have an entry in the ``release.rst`` file::
-
-    $ gvim pavement.py doc/source/release.rst
+run ``towncrier``, which will incorporate the snippets into the 
+``doc/source/release/notes-towncrier.rst`` file, add it to the index, and
+delete the snippets::
+
+    $ towncrier
+    $ gvim doc/source/release/notes-towncrier.rst doc/source/release/2.1.0-notes.rst
+    
+Once the ``notes-towncrier`` contents has been incorporated into 
+the release note it should be cleared and the
+``.. include:: notes-towncrier.rst`` directive removed from the ``2.1.0-notes.rst``.
+The notes will always need some fixups, the introduction will need to be
+written, and significant changes should be called out. For patch releases the
+changelog text may also be appended, but not for the initial release as it is
+too long. Check previous release notes to see how this is done.
 
 
 Release walkthrough
@@ -143,8 +147,8 @@ isn't already present.
 Checkout the branch for the release, make sure it is up to date, and clean the
 repository::
 
-    $ git checkout maintenance/1.21.x
-    $ git pull upstream maintenance/1.21.x
+    $ git checkout maintenance/2.1.x
+    $ git pull upstream maintenance/2.1.x
     $ git submodule update
     $ git clean -xdfq
 
@@ -155,13 +159,13 @@ Sanity check::
 Tag the release and push the tag. This requires write permission for the numpy
 repository::
 
-    $ git tag -a -s v1.21.0 -m"NumPy 1.21.0 release"
-    $ git push upstream v1.21.0
+    $ git tag -a -s v2.1.0 -m"NumPy 2.1.0 release"
+    $ git push upstream v2.1.0
 
 If you need to delete the tag due to error::
 
-   $ git tag -d v1.21.0
-   $ git push --delete upstream v1.21.0
+   $ git tag -d v2.1.0
+   $ git push --delete upstream v2.1.0
 
 
 2. Build wheels
@@ -187,7 +191,7 @@ If a wheel build fails for unrelated reasons, you can rerun it individually:
   the build you want to rerun. On the left there is a list of wheel builds,
   select the one you want to rerun and on the resulting page hit the
   counterclockwise arrows button.
-- On cirrus we haven't figured it out.
+- On cirrus, log into cirrisci, look for the v2.1.0 tag and rerun the failed jobs.
 
 .. _`staging repository`: https://anaconda.org/multibuild-wheels-staging/numpy/files
 .. _`Wheel builder`: https://github.com/numpy/numpy/actions/workflows/wheels.yml
@@ -201,7 +205,7 @@ Anaconda staging directory using the ``tools/download-wheels.py`` script::
 
     $ cd ../numpy
     $ mkdir -p release/installers
-    $ python3 tools/download-wheels.py 1.21.0
+    $ python3 tools/download-wheels.py 2.1.0
 
 
 4. Generate the README files
@@ -221,7 +225,7 @@ after recent PyPI changes, version ``3.4.1`` was used here::
 
     $ cd ../numpy
     $ twine upload release/installers/*.whl
-    $ twine upload release/installers/numpy-1.21.0.tar.gz  # Upload last.
+    $ twine upload release/installers/*.gz  # Upload last.
 
 If one of the commands breaks in the middle, you may need to selectively upload
 the remaining files because PyPI does not allow the same file to be uploaded
@@ -235,18 +239,19 @@ chosen the zip archive.
 6. Upload files to GitHub
 -------------------------
 
-Go to `<https://github.com/numpy/numpy/releases>`_, there should be a ``v1.21.0
-tag``, click on it and hit the edit button for that tag. There are two ways to
-add files, using an editable text window and as binary uploads. Start by
-editing the ``release/README.md`` that is translated from the rst version using
-pandoc. Things that will need fixing: PR lines from the changelog, if included,
-are wrapped and need unwrapping, links should be changed to monospaced text.
-Then copy the contents to the clipboard and paste them into the text window. It
-may take several tries to get it look right. Then
-
-- Upload ``release/installers/numpy-1.21.0.tar.gz`` as a binary file.
+Go to `<https://github.com/numpy/numpy/releases>`_, there should be a ``v2.1.0
+tag``, click on it and hit the edit button for that tag and update the title to
+'v2.1.0 (<date>). There are two ways to add files, using an editable text
+window and as binary uploads. Start by editing the ``release/README.md`` that
+is translated from the rst version using pandoc. Things that will need fixing:
+PR lines from the changelog, if included, are wrapped and need unwrapping,
+links should be changed to monospaced text.  Then copy the contents to the
+clipboard and paste them into the text window. It may take several tries to get
+it look right. Then
+
+- Upload ``release/installers/numpy-2.1.0.tar.gz`` as a binary file.
 - Upload ``release/README.rst`` as a binary file.
-- Upload ``doc/changelog/1.21.0-changelog.rst`` as a binary file.
+- Upload ``doc/changelog/2.1.0-changelog.rst`` as a binary file.
 - Check the pre-release button if this is a pre-releases.
 - Hit the ``{Publish,Update} release`` button at the bottom.
 
@@ -261,7 +266,7 @@ and most patch releases. ``make merge-doc`` clones the ``numpy/doc`` repo into
 ``doc/build/merge`` and updates it with the new documentation::
 
     $ git clean -xdfq
-    $ git co v1.21.0
+    $ git co v2.1.0
     $ rm -rf doc/build  # want version to be current
     $ python -m spin docs merge-doc --build
     $ pushd doc/build/merge
@@ -288,12 +293,12 @@ from ``numpy.org``::
 
 Update the stable link and update::
 
-    $ ln -sfn 1.21 stable
+    $ ln -sfn 2.1 stable
     $ ls -l  # check the link
 
 Once everything seems satisfactory, update, commit and upload the changes::
 
-    $ git commit -a -m"Add documentation for v1.21.0"
+    $ git commit -a -m"Add documentation for v2.1.0"
     $ git push [email protected]:numpy/doc
     $ popd
 
@@ -304,22 +309,22 @@ Once everything seems satisfactory, update, commit and upload the changes::
 Create release notes for next release and edit them to set the version. These
 notes will be a skeleton and have little content::
 
-    $ cp doc/source/release/template.rst doc/source/release/1.21.1-notes.rst
-    $ gvim doc/source/release/1.21.1-notes.rst
-    $ git add doc/source/release/1.21.1-notes.rst
+    $ cp doc/source/release/template.rst doc/source/release/2.1.1-notes.rst
+    $ gvim doc/source/release/2.1.1-notes.rst
+    $ git add doc/source/release/2.1.1-notes.rst
 
 Add new release notes to the documentation release list and update the
 ``RELEASE_NOTES`` variable in ``pavement.py``::
 
     $ gvim doc/source/release.rst pavement.py
 
-Update the ``version`` in ``pyproject.toml`` and ``pyproject.toml.setuppy``::
+Update the ``version`` in ``pyproject.toml``::
 
-    $ gvim pyproject.toml pyproject.toml.setuppy
+    $ gvim pyproject.toml
 
 Commit the result::
 
-    $ git commit -a -m"MAINT: prepare 1.21.x for further development"
+    $ git commit -a -m"MAINT: prepare 2.1.x for further development"
     $ git push origin HEAD
 
 Go to GitHub and make a PR. It should be merged quickly.
@@ -333,7 +338,7 @@ This assumes that you have forked `<https://github.com/numpy/numpy.org>`_::
     $ cd ../numpy.org
     $ git checkout main
     $ git pull upstream main
-    $ git checkout -b announce-numpy-1.21.0
+    $ git checkout -b announce-numpy-2.1.0
     $ gvim content/en/news.md
 
 - For all releases, go to the bottom of the page and add a one line link. Look
@@ -343,7 +348,7 @@ This assumes that you have forked `<https://github.com/numpy/numpy.org>`_::
 
 commit and push::
 
-    $ git commit -a -m"announce the NumPy 1.21.0 release"
+    $ git commit -a -m"announce the NumPy 2.1.0 release"
     $ git push origin HEAD
 
 Go to GitHub and make a PR.
@@ -364,13 +369,13 @@ BCC so that replies will not be sent to that list.
 
 Checkout main and forward port the documentation changes::
 
-    $ git checkout -b post-1.21.0-release-update
-    $ git checkout maintenance/1.21.x doc/source/release/1.21.0-notes.rst
-    $ git checkout maintenance/1.21.x doc/changelog/1.21.0-changelog.rst
-    $ git checkout maintenance/1.21.x .mailmap  # only if updated for release.
+    $ git checkout -b post-2.1.0-release-update
+    $ git checkout maintenance/2.1.x doc/source/release/2.1.0-notes.rst
+    $ git checkout maintenance/2.1.x doc/changelog/2.1.0-changelog.rst
+    $ git checkout maintenance/2.1.x .mailmap  # only if updated for release.
     $ gvim doc/source/release.rst  # Add link to new notes
     $ git status  # check status before commit
-    $ git commit -a -m"MAINT: Update main after 1.21.0 release."
+    $ git commit -a -m"MAINT: Update main after 2.1.0 release."
     $ git push origin HEAD
 
 Go to GitHub and make a PR.