Hacking Rattail

Creating a New Release

The following procedure should be used when creating/publishing a new release.

Test/Commit Changes

This may be obvious, but prior to releasing a new version, all outstanding changes should be tested and committed. Building a release should only happen in a clean repository.

Confirm/Set Version

First the version string should be checked to ensure it reflects the version which is about to be built and released. If the version string is not correct, it should be updated. The version string is found in the file rattail/_version.py.

The version string should always be incremented from that of the previous release according to the nature and quantity of changes since that release. Determining what the new version string should be is an inexact science, but roughly speaking here are “the rules:”

1. During alpha and beta phases, it almost always will be enough to increment only the final number, e.g. going from “0.1b2” to “0.1b3”.
2. Moving from one “phase” to another should only happen when very warranted, and all interested parties should probably be aware/informed of such a move. In this case the version string may change in a way which reflects the move, e.g. from “0.1a7” to “0.1b1”, or from “0.1b9” to “0.1” (the latter signifying a production release).
3. Once the code has reached the production phase, the major and/or minor numbers become subject to increment. Now, if the changes since the last release are more or less minor in nature, then only the minor version number should be incremented and the major version number should remain constant (e.g. going from “0.1” to “0.1.1”).
4. If a more significant change has been introduced (e.g. breaking the API), then the major version number may be incremented, e.g. going from “0.1.4” to “0.2”.

You should be able to verify what the last-released version was by examining previous tags, e.g. with the command:

hg tags | head -n 5

Note

If you had to update the version string as part this step, you must commit the change.

Tag Version

Once the version has been confirmed to be accurate, apply a tag for the version. Assuming your new version is “0.1b7”, the command should be:

hg tag v0.1b7

Note

Tags should always prefix the version string with the small letter “v”.

It’s probably a good idea at this point to push the changes back to the main repository to help alleviate conflicts, and merges in general.

Build/Publish Release

The next step is to actually build the egg and upload it to PyPI. This is basically just a matter of issuing this command:

python setup.py egg_info -b '' bdist_egg sdist register upload

That command will build not only the egg, but a tar-gzipped source distribution as well, and register/upload both to PyPI. It is important to include the egg_info -b '' argument(s); otherwise the version you release will have “.dev” appended to it (e.g. “0.1b7.dev” instead of “0.1b7”).

Note

The registration and uploading of the package to PyPI will require you to have an account and sufficient privileges for the Rattail package. You should already know whether or not you are allowed to do this; if you would like to request permission then please email Lance.

That’s it! At this point anyone and their brother should be able to fetch your latest release with the command:

easy_install -U Rattail

Updating Package Docs

Technically along with a release it will usually be a good idea to update the package’s online documentation as well so that at the very least there will not be a version discrepancy. (The documentation has the version number embedded within it.) However, if you knowingly have altered some thing(s) for which documentation has already been written, now would be the perfect time to edit the docs to reflect your changes. (In a perfect world...)

The documentation can be built with this command, run from the repository root:

python build-docs.py

That will create a file docs.zip in the repository root, which then can be uploaded to PyPI via their web interface.