This section covers releasing your package to PyPI as well as releasing future versions. Your package should have different versions over time: snapshots of a state of the package that you can release to PyPI for instance. These versions should be properly numbered, released and described in a NEWS file. More details below.
After the review process has finished, you're ready to release your package to PyPI so others can find and use your awesome package! Releasing to PyPI is easy. Once your package is ready, register it on PyPI by running:
python setup.py register
When you update your package, you release a new version to PyPI. Fortunately, this is easy! First, we'll talk about the metadata you'll need to update for each version. Then we'll cover how to release your updated version to PyPI manually via the command line or automatically via Travis CI.
Versioning can be done using bumpversion, e.g. for a minor update:
"minor" can be replaced with "major" or "patch" depending on the level of update.
A HISTORY (or NEWS or CHANGELOG) file describing changes associated with each version makes it easier for users to see what's changing in the package and how it might impact their workflow. You must add one for your package, and make it easy to read.
It is mandatory to use a
HISTORYfile in the root of your package. It can also be called NEWS or CHANGELOG We recommend using
[NAME].rstto make the file more browsing-friendly on GitHub (GitHub renders certain file types, including Markdown and reStructured text).
Update the history file before every PyPI release, with a section with the package name, version and date of release.
foobar 0.2.0 (2016-04-01) =========================
Under that header, put in sections as needed, including:
DEPRECATED AND DEFUNCT,
DOCUMENTATION FIXESand any special heading grouping a large number of changes. Under each header, list items as needed. For each item give a description of the new feature, improvement, bug fix, or deprecated function/feature. Link to any related GitHub issue like
(#12)will resolve on GitHub in Releases to a link to that issue in the repo.
After you have added a
git tagand pushed up to GitHub, add the news items for that tagged version to the Release notes of a release in your GitHub repo with a title like
pkgname v0.1.0. See GitHub docs about creating a release.
To manually upload a new package version to PyPI, follow these steps:
- Update your HISTORY file as described above
- Open setup.py and change the version, e.g., version='1.0.3'
- If you added new, non-Python files to the project that need to be distributed as well, e.g., configuration files, add them to MANIFEST.in. This does not need to be done for Python code files ending in .py.
- Open a terminal and go into the parent of the project's root dir
- python setup.py sdist
- Check the resulting files, especially the egg file: are all the files contained?
- If everything is ok, upload the new version to PyPI: python setup.py sdist upload
Instead of manually uploading new package versions, Travis can be configured to automatically upload new versions. If you use this, each time you tag a new release and push it to GitHub, Travis will release it to PyPI (assuming it passes testing).