In a directory outside the pyfits repository, create an activate a
virtualenv in which to do the release (it’s okay to use
--system-site-packages for dependencies like Numpy):
$ virtualenv --system-site-packages --distribute pyfits-release
$ source pyfits-release/bin/activate
Obtain a clean version of the PyFITS repository. That is, one where you
don’t have any intermediate build files. It is best to use a fresh
git clone from the main repository on GitHub without any of the git-svn
configuration. This is because the git-svn support in zest.releaser does not
handle tagging in branches very well yet.
Use git checkout to switch to the appropriate branch from which to do
the release. For a new major or minor release (such as 3.0.0 or 3.1.0)
this should be the ‘master’ branch. When making a bugfix release it is
necessary to switch to the appropriate bugfix branch (e.g.
git checkout 3.1-stable to release 3.1.2 up from 3.1.1).
Install zest.releaser into the virtualenv; use --upgrade --force to
ensure that the latest version is installed in the virtualenv (if you’re
running a csh variant make sure to run rehash afterwards too):
$ pip install zest.releaser --upgrade --force
Install stsci.distutils which includes some additional releaser hooks
that are useful:
$ pip install stsci.distutils --upgrade --force
Ensure that any lingering changes to the code have been committed, then
start the release by running:
You will be asked to enter the version to be released. Press enter to
accept the default (which will normally be correct) or enter a specific
version string. A diff will then be shown of CHANGES.txt and setup.cfg
showing that a release date has been added to the changelog, and that the
version has been updated in setup.cfg. Enter ‘Y’ when asked to commit these
changes.
You will then be shown the command that will be run to tag the release.
Enter ‘Y’ to confirm and run the command.
When asked “Check out the tag (for tweaks or pypi/distutils server upload)”
enter ‘Y’: This feature is used when uploading the source distribution to
our local package index. When asked to ‘Register and upload’ to PyPI enter
‘N’. We will do this manually later in the process once we’ve tested the
release out first. If asked to add the package to the “STScI package
index” enter ‘N’–this package index is no longer being maintained.
You will be asked to enter a new development version. Normally the next
logical version will be selected–press enter to accept the default, or
enter a specific version string. Do not add ”.dev” to the version, as this
will be appended automatically (ignore the message that says ”.dev0 will be
appended”–it will actually be ”.dev” without the 0). For example, if the
just-released version was “3.1.0” the default next version will be “3.1.1”.
If we want the next version to be, say “3.2.0” then that must be entered
manually.
You will be shown a diff of CHANGES.txt showing that a new section has been
added for the new development version, and showing that the version has
been updated in setup.py. Enter ‘Y’ to commit these changes.
When asked to push the changes to a remote repository, enter ‘N’. We want
to test the release out before pushing changes to the remote repository or
registering in PyPI.
When asked to update the PyFITS homepage enter ‘Y’. The enter the name of
the previous version (in the same MAJOR.MINOR.x branch) and then the name
of the just released version. The defaults will usually be correct. When
asked, enter the username and password for your Zope login. As of writing
this is not necessarily the same as your Exchange password. If the update
succeeeds make sure to e-mail IT and ask them to push the updated pages
from the test site to the production site.
This should complete the portion of the process that’s automated at this point
(though future versions will automate these steps as well, after a few needed
features are added to zest.releaser).
Check out the tag of the released version. For example:
Create the source distribution by doing:
Now, outside the repository create and activate another new virtualenv
for testing the release:
$ virtualenv --system-site-packages --distribute pyfits-release-test
$ source pyfits-release-test/bin/activate
Use pip to install the source distribution built in step 13 into the
new test virtualenv. This will look something like:
$ pip install PyFITS/dist/pyfits-3.2.0.tar.gz
where the path should be to the sole .tar.gz file in the dist/
directory under your repository clone.
Try running the tests in the installed PyFITS:
$ pip install nose --force --upgrade
$ nosetests pyfits
If any of the tests fail abort the process and start over. Undo the
previous two git commits (the one tagged as the release, and the one
where you bumped to the next dev version):
$ git reset --hard HEAD^^
Also delete the newly created tag:
Resolve the test failure, commit any new fixes, and start the release
procedure over again (it’s rare for this to be an issue if the tests
passed before starting the release, but it is possible–the most likely
case being if some file that should be installed is either not getting
installed or is not included in the source distribution in the first
place).
Assuming the test installation worked, change directories back into the
repository and push the new tag/release to the main repository on GitHub:
This initial step is necessary since the tag was made off of a pure git
commit. But when we synchronize with SVN the commit history will change
so we need to force an additional push to the GitHub repository:
$ git svn dcommit
$ git push --force
Then register the release on PyPI with:
$ python setup.py register
Upload the source distribution to PyPI; this is preceded by re-running the
sdist command, which is necessary for the upload command to know which
distribution to upload:
$ python setup.py sdist upload
After registering on PyPI go to the URL:
https://pypi.python.org/pypi?%3Aaction=pkg_edit&name=pyfits
and mark any previous releases superceded by this release as hidden via the
web UI. Don’t check “Auto-hide old releases” as we want to support
discovery of bugfix releases of older versions.
When releasing a new major or minor version, create a bugfix branch for
that version. Starting from the tagged changset, just checkout a new
branch and push it to the remote server. For example, after releasing
version 3.2.0, do:
$ git checkout -b 3.2-stable
Then edit the setup.cfg so that the version is '3.2.1.dev', and commit
that change. Then, do:
$ git push origin +3.2-stable
Note
You may need to replace origin here with upstream or whatever
remote name you use for the main PyFITS repository on GitHub.
The purpose of this branch is for creating bugfix releases like “3.2.1” and
“3.2.2”, while allowing development of new features to continue in the
master branch. Only changesets that fix bugs without making significant
API changes should be merged to the bugfix branches.
On the other hand, if a bugfix release was made, the CHANGES.txt file
will only be updated in the stable branch; the master branch also needs to
be updated so that the release is reflected in its copy of CHANGES.txt.
Just run:
Say 3.2.1 was just released. Use git log -p to find the commit
that updated the changelog with the release date in the stable branch,
like:
Copy the commit hash, and then cherry-pick it into master:
$ git cherry-pick <sha1 hash>
You will likely have to resolve a merge conflict, but just make sure that
the section heading for the just released version is updated so that
“(unreleased)” is replaced with today’s date. Also ensure that a new
section is added for the next bugfix release in that release series.
Log into the Read the Docs control panel for PyFITS at
https://readthedocs.org/projects/pyfits/. Click on “Admin” and then
“Versions”. Find the just-released version (it might not appear for a few
minutes) and click the check mark next to “Active” under that version.
Leave the dropdown list on “Public”, then scroll to the bottom of the page
and click “Submit”. If this is the release with the highest version
number, make sure to set it as the “default” version as soon as the build
finishes.
Note: When you first activate the new version in Read the Docs, it
immediately displays a “Build Failed” message for the build of the new
docs. This is a bug–all it really means is that those docs have never
been built yet. Give it a few minutes before checking that the build
succeeded. Then you can set that version as the default if needed.
We also mirror the most recent documentation at pythonhosted.org/pyfits (
formerly packages.python.org).
First it is necessary to build the docs manually. Make sure all the
dependencies are satisfied by running:
Then change directories into the docs/ directory and install the additional
requirements for the docs:
$ cd docs
$ pip install -r requirements.txt
Then make the HTML docs:
Now change directories back to the source root and upload:
$ cd ..
$ python setup.py upload_docs
Mark the milestone of the released version as closed/completed in the
PyFITS bug tracker(s). If asked for a timestamp (as Trac does) use the
timestamp of the git tag made for the release.
Build and upload the Windows installers:
Launch a MinGW shell.
Just as before make sure you have a pypirc file in your home
directory with your authentication info for PyPI. On Windows the file
should be called just pypirc without the leading . because
having some consistency would make this too easy :)
Do a git clone of the repository or, if you already have a clone
of the repository do git fetch --tags to get the new tags.
Check out the tag for the just released version. For example:
(ignore the message about being in “detached HEAD” state).
For each Python version installed, build with the mingw32 compiler,
create the binary installer, and upload it. It’s best to use the full
path to each Python version to avoid ambiguity. It is also best to
clean the repository between builds for each version. For example:
$ /C/Python25/python setup.py build -c mingw32 bdist_wininst upload
< ... builds and uploads successfully ... >
$ git clean -dfx
$ /C/Python26/python setup.py build -c mingw32 bdist_wininst upload
< ... builds and puloads successfully ... >
$ git clean -dfx
$ < ... and so on, for all currently supported Python versions ... >
