Join GitHub today
GitHub is home to over 28 million developers working together to host and review code, manage projects, and build software together.Sign up
This document outlines how to manage the MDAnalysis sources and how to prepare distribution packages. See also DevelopmentWorkflow for new ideas how to organize codebase and workflow.
Release policy and release numbering
We use a MAJOR.MINOR.PATCH scheme to label releases. We adhere to the idea of semantic versioning (semantic versioning was introduced with release 0.9, see Issue 200): Given a version number MAJOR.MINOR.PATCH, we increment the:
- MAJOR version when we make incompatible API changes,
- MINOR version when we add functionality in a backwards-compatible manner, and
- PATCH version when we make backwards-compatible bug fixes.
However, as long as the MAJOR number is 0 (i.e. the API has not stabilized), even MINOR increases may introduce incompatible API changes. As soon as we have a 1.0.0 release, the public API can only be changed in a backward-incompatible manner with an increase in MAJOR version.
Additional labels for pre-release and build metadata are available as extensions to the MAJOR.MINOR.PATCH format.
The CHANGELOG lists important changes for each release.
MAJOR, MINOR, PATCH number are integers that increase monotonically.
The release number is set in setup.py and in
MDAnalysis.__version__ (MDAnalysis/version.py), e.g.
RELEASE = '0.7.5'
While the code is in development (i.e. whenever we are not preparing a release!) the release number gets the suffix -dev0, e.g.
RELEASE = '0.7.6-dev0'
so that people using the development branch from the sources see immediately that this is not a final release. For example, "0.7.6-dev0" is the state before the 0.7.6 release.
git repository: branches
Releases should exist on the master branch:
- declare feature freeze on develop via developer list
- finalise the CHANGELOG file with date
- merge develop into master (make sure that it gets the full release number)
- increment version
- rebuild c files (See Issue #667)
- tag the release
Preparing distribution tar balls
- Update local repository (
git pull) and make sure that there are no conflicts.
- Update CHANGELOG with the release number and summarize important changes. Add all authors that contributed to this release. See the file itself for guidelines and formatting.
- Commit updated tree
MDAnalysis.__version__(MDAnalysis/version.py); note that there is a
setup.pyin the MDAnalysis package and the MDAnalysisTests testsuite!). There's a script
maintain/change_release.shthat typically does the job:
- Make sure to add and commit the changes!
- Test if the distribution (MDAnalysis and MDAnalysisTests) builds successfully and run the UnitTests:
- Fix code so that all tests are passed (except for known failures). Note that if you worked on any of the Cython code then you should check that the new code was also compiled (monitor the output from
python setup.py build).
Note on Cython code (see Issue 85 for details):
- If no Cython,
setup.pywill use C-code that was previously generated; of you updated any
*.pyxfiles then you must have Cython installed (but you probably new this already).
- If Cython if installed, it is used to compile extension and
.pyxsource files are used instead of
- From there,
.pyxfiles are converted to
.cfiles if they are newer than the already present
.cfiles or if the
--forceflag is set (e.g
setup.py build --force).
Therefore, as a developer you should (1) have Cython installed and (2) only use
--forceif you are positive that you want to regenerate all
- commit any changes and fixes that were necessary to make it work with
- Build a source distribution tar ball with
# MDAnalysis cd package rm -f setup.cfg python setup.py sdist # MDAnalysisTests cd ../testsuite python setup.py sdist
This builds the distribution under
Unpack the distribution in a tmp directory and try to build it:
mkdir tmp && cd tmp tar -zxvf ../dist/MDAnalysis-0.7.5.tar.gz cd MDAnalysis-0.7.5 python setup.py build --build-lib=.
The new test cases should be in your system as developer installation (from the previous step) so you should be able to run the UnitTests (run
python from the same directory):
>>> import MDAnalysis.tests >>> MDAnalysis.tests.test(label='full', extra_argv=['--exe'])
(this imports the module compiled in
The above should work at least on Linux and Mac OS X. If it fails then go back and fix things and do not release.
If everything works then we are now reasonably confident that a user can also compile and use the package so we push the source code for the release to the master repository. Push it to the master with
git push origin master
(or similar command).
The distribution is now ready. Tag it in git:
git tag -m 'release 0.7.5 of MDAnalysis and MDAnalysisTests' release-0.7.5 git push --tags origin master
The tag format is the string release- followed by major.minor.patch.
Upload to PyPi
- upload the source distribution tar balls of MDAnalysis and MDAnalysisTests to the python package index (e.g. using
twine upload -r pypi dist/MDAnalysis-0.16.2.tar.gz
(you need to have run
python setup.py register at least once before).
- build the docs and upload to PyPi
- make the new tar ball a featured release so that it shows up on the front page (and unfeature any older releases).
- provide a short description (a condensed version of the
Update/create a release page on the wiki
Update docs on PyPI
Since 0.7.4 there's also a MDAnalysis page on PyPi (the Python Package Index).
For full releases we have the documentation at http://packages.python.org/MDAnalysis/ . It is updated by building and then zipping the html docs and uploading manually:
cd package/doc/sphinx make html cd ../html zip -r ../pypidoc.zip *
Then upload documentation (the file
pypidoc.zip) via the MDAnalysis: Edit page.
Update release on anaconda
Update the release version and build the package in one vagrant box from this repo.
anaconda upload -u MDAnalysis /path/to/build/package/mdanalysis-version-py27_0.tar.bz
The library, MDAnalysis and the tests, MDAnalysisTests share the same release number: whenever there's a new MDAnalysis there will be a corresponding MDAnalysisTests. Therefore, the two packages are maintained and built together (see above).