313 lines
11 KiB
ReStructuredText
313 lines
11 KiB
ReStructuredText
This file contains a walkthrough of the NumPy 1.14.5 release on Linux, modified
|
|
for building on azure and uploading to anaconda.org
|
|
The commands can be copied into the command line, but be sure to
|
|
replace 1.14.5 by the correct version.
|
|
|
|
This should be read together with the general directions in `releasing`.
|
|
|
|
|
|
Release Walkthrough
|
|
====================
|
|
|
|
Note that in the code snippets below, ``upstream`` refers to the root repository on
|
|
github and ``origin`` to a fork in your personal account. You may need to make adjustments
|
|
if you have not forked the repository but simply cloned it locally. You can
|
|
also edit ``.git/config`` and add ``upstream`` if it isn't already present.
|
|
|
|
|
|
Backport Pull Requests
|
|
----------------------
|
|
|
|
Changes that have been marked for this release must be backported to the
|
|
maintenance/1.14.x branch.
|
|
|
|
|
|
Update Release documentation
|
|
----------------------------
|
|
|
|
The file ``doc/changelog/1.14.5-changelog.rst`` should be updated to reflect
|
|
the final list of changes and contributors. This text can be generated by::
|
|
|
|
$ python tools/changelog.py $GITHUB v1.14.4..maintenance/1.14.x > doc/changelog/1.14.5-changelog.rst
|
|
|
|
where ``GITHUB`` contains your github access token. This text may also be
|
|
appended to ``doc/release/1.14.5-notes.rst`` for release updates, though not
|
|
for new releases like ``1.14.0``, as the changelogs for ``*.0`` releases tend to be
|
|
excessively long. The ``doc/source/release.rst`` file should also be
|
|
updated with a link to the new release notes. These changes should be committed
|
|
to the maintenance branch, and later will be forward ported to master.
|
|
|
|
|
|
Finish the Release Note
|
|
-----------------------
|
|
|
|
.. note:
|
|
|
|
This has changed now that we use ``towncrier``. See the instructions for
|
|
creating the release note in ``doc/release/upcoming_changes/README.rst``.
|
|
|
|
Fill out the release note ``doc/release/1.14.5-notes.rst`` calling out
|
|
significant changes.
|
|
|
|
|
|
Prepare the release commit
|
|
--------------------------
|
|
|
|
Checkout the branch for the release, make sure it is up to date, and clean the
|
|
repository::
|
|
|
|
$ git checkout maintenance/1.14.x
|
|
$ git pull upstream maintenance/1.14.x
|
|
$ git submodule update
|
|
$ git clean -xdfq
|
|
|
|
Edit pavement.py and setup.py as detailed in HOWTO_RELEASE::
|
|
|
|
$ gvim pavement.py setup.py
|
|
$ git commit -a -m"REL: NumPy 1.14.5 release."
|
|
|
|
Sanity check::
|
|
|
|
$ python3 runtests.py -m "full"
|
|
|
|
Push this release directly onto the end of the maintenance branch. This
|
|
requires write permission to the numpy repository::
|
|
|
|
$ git push upstream maintenance/1.14.x
|
|
|
|
As an example, see the 1.14.3 REL commit: `<https://github.com/numpy/numpy/commit/73299826729be58cec179b52c656adfcaefada93>`_.
|
|
|
|
|
|
Build source releases
|
|
---------------------
|
|
|
|
Paver is used to build the source releases. It will create the ``release`` and
|
|
``release/installers`` directories and put the ``*.zip`` and ``*.tar.gz``
|
|
source releases in the latter. ::
|
|
|
|
$ python3 -m cython --version # check for correct cython version
|
|
$ paver sdist # sdist will do a git clean -xdf, so we omit that
|
|
|
|
|
|
Build wheels
|
|
------------
|
|
|
|
Trigger the wheels build by pointing the numpy-wheels repository at this
|
|
commit. This can take up to an hour. The numpy-wheels repository is cloned from
|
|
`<https://github.com/MacPython/numpy-wheels>`_. Start with a pull as the repo
|
|
may have been accessed and changed by someone else and a push will fail::
|
|
|
|
$ cd ../numpy-wheels
|
|
$ git pull upstream master
|
|
$ git branch <new version> # only when starting new numpy version
|
|
$ git checkout v1.14.x # v1.14.x already existed for the 1.14.4 release
|
|
|
|
Edit the ``azure/posix.yml`` and ``azure/windows.yml`` files to make sure they
|
|
have the correct version, and put in the commit hash for the ``REL`` commit
|
|
created above for ``BUILD_COMMIT``, see an _example::
|
|
|
|
$ gvim azure/posix.yml azure/windows.yml
|
|
$ git commit -a
|
|
$ git push upstream HEAD
|
|
|
|
Now wait. If you get nervous at the amount of time taken -- the builds can take
|
|
a while -- you can check the build progress by following the links
|
|
provided at `<https://github.com/MacPython/numpy-wheels>`_ to check the
|
|
build status. Check if all the needed wheels have been built and
|
|
uploaded before proceeding. There should currently be 21 of them at
|
|
`<https://anaconda.org/multibuild-wheels-staging/numpy/files>`_, 3 for Mac, 6
|
|
for Windows, and 12 for Linux.
|
|
|
|
.. example_: https://github.com/MacPython/numpy-wheels/pull/80/commits/cbf4af4
|
|
|
|
Note that sometimes builds, like tests, fail for unrelated reasons and
|
|
you will need to restart them.
|
|
|
|
Download wheels
|
|
---------------
|
|
|
|
When the wheels have all been successfully built, download them using the ``wheel-uploader``
|
|
in the ``terryfy`` repository. The terryfy repository may be cloned from
|
|
`<https://github.com/MacPython/terryfy>`_ if you don't already have it. The
|
|
wheels can also be uploaded using the ``wheel-uploader``, but we prefer to
|
|
download all the wheels to the ``../numpy/release/installers`` directory and
|
|
upload later using ``twine``::
|
|
|
|
$ cd ../terryfy
|
|
$ git pull upstream master
|
|
$ CDN_URL=https://anaconda.org/multibuild-wheels-staging/numpy/files
|
|
$ NPY_WHLS=../numpy/release/installers
|
|
$ ./wheel-uploader -u $CDN_URL -n -v -w $NPY_WHLS -t win numpy 1.14.5
|
|
$ ./wheel-uploader -u $CDN_URL -n -v -w $NPY_WHLS -t manylinux1 numpy 1.14.5
|
|
$ ./wheel-uploader -u $CDN_URL -n -v -w $NPY_WHLS -t macosx numpy 1.14.5
|
|
|
|
If you do this often, consider making CDN_URL and NPY_WHLS part of your default
|
|
environment.
|
|
|
|
Generate the README files
|
|
-------------------------
|
|
|
|
This needs to be done after all installers are downloaded, but before the pavement
|
|
file is updated for continued development::
|
|
|
|
$ cd ../numpy
|
|
$ paver write_release
|
|
|
|
|
|
Tag the release
|
|
---------------
|
|
|
|
Once the wheels have been built and downloaded without errors, go back to your
|
|
numpy repository in the maintenance branch and tag the ``REL`` commit, signing
|
|
it with your gpg key::
|
|
|
|
$ git tag -s v1.14.5
|
|
|
|
You should upload your public gpg key to github, so that the tag will appear
|
|
"verified" there.
|
|
|
|
Check that the files in ``release/installers`` have the correct versions, then
|
|
push the tag upstream::
|
|
|
|
$ git push upstream v1.14.5
|
|
|
|
We wait until this point to push the tag because it is public and should not
|
|
be changed after it has been pushed.
|
|
|
|
|
|
Reset the maintenance branch into a development state
|
|
-----------------------------------------------------
|
|
|
|
Add another ``REL`` commit to the numpy maintenance branch, which resets the
|
|
``ISREALEASED`` flag to ``False`` and increments the version counter::
|
|
|
|
$ gvim pavement.py setup.py
|
|
|
|
Create release notes for next release and edit them to set the version::
|
|
|
|
$ cp doc/source/release/template.rst doc/source/release/1.14.6-notes.rst
|
|
$ gvim doc/source/release/1.14.6-notes.rst
|
|
$ git add doc/source/release/1.14.6-notes.rst
|
|
|
|
Add new release notes to the documentation release list::
|
|
|
|
$ gvim doc/source/release.rst
|
|
|
|
Commit the result::
|
|
|
|
$ git commit -a -m"REL: prepare 1.14.x for further development"
|
|
$ git push upstream maintenance/1.14.x
|
|
|
|
|
|
Upload to PyPI
|
|
--------------
|
|
|
|
Upload to PyPI using ``twine``. A recent version of ``twine`` of is needed
|
|
after recent PyPI changes, version ``1.11.0`` was used here.
|
|
|
|
.. code-block:: sh
|
|
|
|
$ cd ../numpy
|
|
$ twine upload release/installers/*.whl
|
|
$ twine upload release/installers/numpy-1.14.5.zip # Upload last.
|
|
|
|
If one of the commands breaks in the middle, which is not uncommon, you may
|
|
need to selectively upload the remaining files because PyPI does not allow the
|
|
same file to be uploaded twice. The source file should be uploaded last to
|
|
avoid synchronization problems if pip users access the files while this is in
|
|
process. Note that PyPI only allows a single source distribution, here we have
|
|
chosen the zip archive.
|
|
|
|
|
|
Upload files to github
|
|
----------------------
|
|
|
|
Go to `<https://github.com/numpy/numpy/releases>`_, there should be a ``v1.14.5
|
|
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.
|
|
|
|
- Cut and paste the ``release/README.md`` file contents into the text window.
|
|
- Upload ``release/installers/numpy-1.14.5.tar.gz`` as a binary file.
|
|
- Upload ``release/installers/numpy-1.14.5.zip`` as a binary file.
|
|
- Upload ``release/README.rst`` as a binary file.
|
|
- Upload ``doc/changelog/1.14.5-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.
|
|
|
|
|
|
Upload documents to numpy.org
|
|
-----------------------------
|
|
|
|
This step is only needed for final releases and can be skipped for
|
|
pre-releases. ``make merge-doc`` clones the ``numpy/doc`` repo into
|
|
``doc/build/merge`` and updates it with the new documentation::
|
|
|
|
$ pushd doc
|
|
$ make dist
|
|
$ make merge-doc
|
|
$ popd
|
|
|
|
If the release series is a new one, you will need to add a new section to the
|
|
``doc/build/merge/index.html`` front page just after the "insert here" comment::
|
|
|
|
$ gvim doc/build/merge/index.html +/'insert here'
|
|
|
|
Otherwise, only the ``zip`` and ``pdf`` links should be updated with the
|
|
new tag name::
|
|
|
|
$ gvim doc/build/merge/index.html +/'tag v1.14'
|
|
|
|
You can "test run" the new documentation in a browser to make sure the links
|
|
work::
|
|
|
|
$ firefox doc/build/merge/index.html
|
|
|
|
Once everything seems satisfactory, commit and upload the changes::
|
|
|
|
$ pushd doc/build/merge
|
|
$ git commit -am"Add documentation for v1.14.5"
|
|
$ git push
|
|
$ popd
|
|
|
|
Announce the release on scipy.org
|
|
---------------------------------
|
|
|
|
This assumes that you have forked `<https://github.com/scipy/scipy.org>`_::
|
|
|
|
$ cd ../scipy.org
|
|
$ git checkout master
|
|
$ git pull upstream master
|
|
$ git checkout -b numpy-1.14.5
|
|
$ gvim www/index.rst # edit the News section
|
|
$ git commit -a
|
|
$ git push origin HEAD
|
|
|
|
Now go to your fork and make a pull request for the branch.
|
|
|
|
|
|
Announce to mailing lists
|
|
-------------------------
|
|
|
|
The release should be announced on the numpy-discussion, scipy-devel,
|
|
scipy-user, and python-announce-list mailing lists. Look at previous
|
|
announcements for the basic template. The contributor and PR lists are the same
|
|
as generated for the release notes above. If you crosspost, make sure that
|
|
python-announce-list is BCC so that replies will not be sent to that list.
|
|
|
|
|
|
Post-Release Tasks
|
|
------------------
|
|
|
|
Checkout master and forward port the documentation changes::
|
|
|
|
$ git checkout -b update-after-1.14.5-release
|
|
$ git checkout maintenance/1.14.x doc/source/release/1.14.5-notes.rst
|
|
$ git checkout maintenance/1.14.x doc/changelog/1.14.5-changelog.rst
|
|
$ gvim doc/source/release.rst # Add link to new notes
|
|
$ git add doc/changelog/1.14.5-changelog.rst doc/source/release/1.14.5-notes.rst
|
|
$ git status # check status before commit
|
|
$ git commit -a -m"REL: Update master after 1.14.5 release."
|
|
$ git push origin HEAD
|
|
|
|
Go to github and make a PR.
|