PackageChecklist

Release checklist for diffpy.SomeThing package.

See the trunk directory https://github.com/diffpy/diffpy.srreal for reference examples (so far a work in progress)

Source Files

1. all Python sources start with a hash-bang line '#!/usr/bin/env python'
2. executable bit is set only for source files that are intended to be run as a script
3. Remove all __id__ = "$Id$" lines. We do not use subversion keyword expansion anymore.
4. No trailing spaces, no Windows CRLF line ends, no TAB characters at all.

User manual

1. The package contains doc/manual directory with sphinx documentation project set up as for diffpy.srreal.
2. make html compiles with no warnings and make publish does push to the gh-pages branch.
3. For package diffpy.SomeThing the URL http://diffpy.github.io/doc/SomeThing redirects to http://diffpy.github.io/diffpy.SomeThing, i.e., the published gh-pages branch from the main GitHub repository.

README.rst

File has .rst extension and is written in reStructuredText (rst) format. For a primer on rst syntax see http://sphinx-doc.org/rest.html or look at the README.rst file in the pyobjcryst package.

First line is the package full name with a few-word description. This is followed by a paragraph with more detailed description of package functionality and with a URL of the user manual at http://www.diffpy.org/doc/SomeThing/ http://diffpy.github.io/diffpy.SomeThing.

REQUIREMENTS section lists the dependencies needed to install the package, the sudo apt-get install command for Linux and port install command for MacPorts.

INSTALLATION section gives installation command-lines for python setup.py install and easy_install diffpy.FixMe.

DEVELOPMENT CONTRIBUTION section should give the project GitHub URL, show how to install the package in a developer mode, encourage contributors to fork it and send us pull requests.

CONTACTS section gives package GitHub URL, the main project URL at www.diffpy.org and Simon as the main contact person.

AUTHORS.txt

The file lists package authors one per line ordered by their contributions. Simon is included in the list.

LICENSE.txt

License text is the approved BNL license. If not available, create an issue in the package GitHub repository.

setup.py

1. File docstring gives full Python name of the package, brief description of its functionality, and lists executable scripts that get installed if any.

2. version is extracted from git data, python setup.py egg_info updates diffpy/FixMe/version.cfg and sets it to right values.

3. install_requires includes any necessary diffpy dependencies or lightweight packages from PyPI. It must NOT include any dependencies that are in the system package manager; those belong to the REQUIREMENTS section of README.txt.

4. dependency_links is set to ['http://www.diffpy.org/packages/']
   dependency_links entry is removed or set to [].

5. url points to the package GitHub page

6. author and author_email are set as:

   author = "Simon J.L. Billinge group",
   author_email = "[email protected]",

7. maintainter and maintainer_email are set to the current package maintainer

8. license is set to "BSD, see LICENSE.txt"

9. keywords are set and meaningful

10. include_package_data = True - this will include any data files that are under the diffpy directory (e.g., .../version.cfg, .../tests/testdata).
    If package needs any other data files, list them in the data_files entry.

11. test_suite is diffpy.FixMe.tests.run, python setup.py test works

12. zip_safe is False

13. classifiers are up-to-date and include anything relevant from https://pypi.python.org/pypi?%3Aaction=list_classifiers

MANIFEST.in

1. includes all sources, package data files, txt files, version.cfg
2. excludes build, dist, doc directories, MANIFEST.in, any non-essential temporary or development related files.

Tests

1. check that a source bundle from python setup.py sdist --keep-temp contains correct files.
2. test installation from a source bundle to virtual Python environment works and passes all tests. Example:

   virtualenv --system-site-packages /tmp/tenv1
   source /tmp/tenv1/bin/activate
   easy_install TheSourceTarBall
   
   # verify location and version of the installed package, ie,
   # the FILE and VERSION values in pydoc output
   cd /tmp      # get out from the package source tree
   python -m pydoc diffpy.FixMe
   
   # execute package unit tests
   python -m diffpy.FixMe.tests.run

3. Check that python setup.py install run from the git repository produces working installation (reuse the virtualenv and test commands from above)
4. Check that python setup.py test run in the git repo executes unit tests and they all pass.

Conda release checklist

1. merge branch license from diffpy/diffpy-release
2. fix issues reported by pyflakes
3. update README.rst with conda information
4. make sure build number in meta.yaml is 0
5. make sure conda in travis uses only the diffpy channel
6. update FALLBACK_VERSION to the new release number X.Y
7. create signed tag vX.Y, include list of changes since previous release in tag description
8. create conda packages and upload them to the diffpy channel
9. use makesdist to create tar bundle
10. create new release on github. For C++ packages attach source archive and include its MD5 on the release page.
11. use twine to upload the tar bundle to PyPI.
12. rebuild the manual and push it to the gh-pages branch.

Resources

Gist with pywhichmodule and pypath scripts that should help with verifying package installation.