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:"

#. 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".

#. 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).

#. 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").

#. 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
<http://pypi.python.org/>`_.  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 <lance@edbob.org>`_.

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 <http://packages.python.org/Rattail/>`_ 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
<http://pypi.python.org/pypi?%3Aaction=pkg_edit&name=Rattail>`_.