The current info on building and releasing NumPy and SciPy is scattered in
several places. It should be summarized in one place, updated, and where
necessary described in more detail. The sections below list all places where
useful info can be found.

Python 2.7 and >=3.4 are the currently supported versions when building from
source. We test NumPy against all these versions every time we merge code to
master. Binary installers may be available for a subset of these versions (see
below).

Python 2.7 and >=3.4 are the versions for which we provide binary installers.
OS X versions >= 10.6 are supported. We build binary wheels for OSX that are
compatible with Python.org Python, system Python, homebrew and macports - see
this OSX wheel building summary for details.

We build 32- and 64-bit wheels for Python 2.7, 3.4, 3.5 on Windows. Windows
XP, Vista, 7, 8 and 10 are supported. We build NumPy using the MSVC compilers
on Appveyor, but we are hoping to update to a mingw-w64 toolchain. The Windows wheels use ATLAS for BLAS / LAPACK.

We build all our wheels on cloud infrastructure - so this list of compilers is
for information and debugging builds locally. See the .travis.yml and
appveyor.yml scripts in the numpy wheels repo for the definitive source
of the build recipes. Packages that are available using pip are noted.

The same gcc version is used as the one with which Python itself is built on
each platform. At the moment this means:

OS X builds on travis currently use clang. It appears that binary wheels
for OSX >= 10.6 can be safely built from the travis-ci OSX 10.9 VMs
when building against the Python from the Python.org installers;

Windows builds use the MSVC version corresponding to the Python being built
against;

Manylinux1 wheels use the gcc provided on the Manylinux docker images.

You will need Cython for building the binaries. Cython compiles the .pyx
files in the NumPy distribution to .c files.

A typical release schedule is one beta, two release candidates and a final
release. It’s best to discuss the timing on the mailing list first, in order
for people to get their commits in on time, get doc wiki edits merged, etc.
After a date is set, create a new maintenance/x.y.z branch, add new empty
release notes for the next version in the master branch and update the Trac
Milestones.

Before the release branch is made, it should be checked that all deprecated
code that should be removed is actually removed, and all new deprecations say
in the docstring or deprecation warning at what version the code will be
removed.

If the API has changed, increment the C_API_VERSION in setup_common.py. The
API is unchanged only if any code compiled against the current API will be
backward compatible with the last released NumPy version. Any changes to
C structures or additions to the public interface will make the new API
not backward compatible.

If the C_API_VERSION in the first step has changed, or if the hash of
the API has changed, the cversions.txt file needs to be updated. To check
the hash, run the script numpy/core/cversions.py and note the API hash that
is printed. If that hash does not match the last hash in
numpy/core/code_generators/cversions.txt the hash has changed. Using both
the appropriate C_API_VERSION and hash, add a new entry to cversions.txt.
If the API version was not changed, but the hash differs, you will need to
comment out the previous entry for that API version. For instance, in NumPy
1.9 annotations were added, which changed the hash, but the API was the
same as in 1.8. The hash serves as a check for API changes, but it is not
definitive.

If steps 1 and 2 are done correctly, compiling the release should not give
a warning “API mismatch detect at the beginning of the build”.

The numpy/core/include/numpy/numpyconfig.h will need a new
NPY_X_Y_API_VERSION macro, where X and Y are the major and minor version
numbers of the release. The value given to that macro only needs to be
increased from the previous version if some of the functions or macros in
the include files were deprecated.

The C ABI version number in numpy/core/setup_common.py should only be
updated for a major release.

Do any other changes. When you are ready to release, do the following
changes:

diff--gita/setup.pyb/setup.pyindexb1f53e3..8b36dbe100755---a/setup.py+++b/setup.py@@-57,7+57,7@@PLATFORMS=["Windows","Linux","Solaris","Mac OS-MAJOR=1MINOR=7MICRO=0-ISRELEASED=False+ISRELEASED=TrueVERSION='%d.%d.%drc1'%(MAJOR,MINOR,MICRO)# Return the git revision as a string

And make sure the VERSION variable is set properly.

Now you can make the release commit and tag. We recommend you don’t push
the commit or tag immediately, just in case you need to do more cleanup. We
prefer to defer the push of the tag until we’re confident this is the exact
form of the released code (see: Push the release tag and commit):

git commit -s -m “REL: Release.” setup.py
git tag -s <version>

The -s flag makes a PGP (usually GPG) signed tag. Please do sign the
release tags.

The release tag should have the release number in the annotation (tag
message). Unfortunately, the name of a tag can be changed without breaking the
signature, the contents of the message cannot.

NPY_RELAXED_STRIDE_CHECKING was made the default in NumPy 1.10.0 and bogus
strides are used in the development branch to smoke out problems. The
patch should be updated if
necessary and applied to the release branch to rationalize the strides.

The tar-files and binary releases for distribution should be uploaded to SourceForge,
together with the Release Notes and the Changelog. Uploading can be done
through a web interface or, more efficiently, through scp/sftp/rsync as
described in the SourceForge
upload guide (dead link).
For example:

You should upload the wheels first, and the source formats last, to make sure
that pip users don’t accidentally get a source install when they were
expecting a binary wheel.

You can do this automatically using the wheel-uploader script from
https://github.com/MacPython/terryfy. Here is the recommended incantation for
downloading all the Windows, Manylinux, OSX wheels and uploading to PyPI.

The -v flag gives verbose feedback, -s causes the script to sign the
wheels with your GPG key before upload. Don’t forget to upload the wheels
before the source tarball, so there is no period for which people switch from
an expected binary install to a source install from PyPI.

There are two ways to update the source release on PyPI, the first one is:

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.

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.

Trigger the wheels build by pointing the numpy-wheels repository at this
commit. This can take a while. 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:

Now wait. If you get nervous at the amount of time taken – the builds can take
several hours– you can check the build progress by following the links
provided at https://github.com/MacPython/numpy-wheels to check the travis
and appveyor build status. Check if all the needed wheels have been built and
uploaded before proceeding. There should currently be 22 of them at
https://wheels.scipy.org, 4 for Mac, 8 for Windows, and 10 for Linux.
Note that sometimes builds, like tests, fail for unrelated reasons and you will
need to restart them.

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:

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.

Go to https://github.com/numpy/numpy/releases, there should be a v1.14.5tag, 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.

This step is only needed for final releases and can be skipped for
pre-releases. You will also need upload permission for the document server, if
you do not have permission ping Pauli Virtanen or Ralf Gommers to generate and
upload the documentation. Otherwise:

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.