Entrypoints documentation
=========================

**Warning**: *entry points were added in 3.0, I'm reserving the right to make
backwards-incompatible changes to the entry point mechanism in the next couple
of releases.  It is a major new piece of functionality for zest.releaser and
getting all the details right at the first attempt isn't guaranteed.*

A zest.releaser entrypoint gets passed a data dictionary and that's about it.
You can do tasks like generating documentation.  Or downloading external files
you don't want to store in your repository but that you do want to have
included in your egg.

Every release step (prerelease, release and postrelease) has three points
where you can hook in an entry point:

before
    Only the ``workingdir`` and ``name`` are available in the data
    dictionary, nothing has happened yet.

middle
    All data dictionary items are available and some questions (like new
    version number) have been asked.  No filesystem changes have been made
    yet.

after
    The action has happened, everything has been written to disk or uploaded
    to pypi or whatever.


For the release step it made sense to create one extra entry point:

after_checkout
    The middle entry point has been handled, the tag has been made, a
    checkout of that tag has been made and we are now in that checkout
    directory.  Of course, when the user chooses not to do a checkout,
    this entry point never triggers.

Note that an entry point can be specific for one package (usually the
package that you are now releasing) or generic for all packages.  An
example of a generic one is `gocept.zestreleaser.customupload`_, which
offers to upload the generated distribution to a chosen destination
(like a server for internal company use).  If your entry point is
specific for the current package only, you should add an extra check
to make sure it is not run while releasing other packages; something
like this should do the trick::

    def my_entry_point(data):
        if data['name'] != 'my.package':
            return
        ...

.. _`gocept.zestreleaser.customupload`: http://pypi.python.org/pypi/gocept.zestreleaser.customupload


Entry point specification
-------------------------

An entry point is configured like this in your setup.py::

      entry_points={
          #'console_scripts': [
          #    'myscript = my.package.scripts:main'],
          'zest.releaser.prereleaser.middle': [
              'dosomething = my.package.some:some_entrypoint',
              ]},

Replace ``prereleaser`` and ``middle`` in ``zest.releaser.prereleaser.middle``
with prerelease/release/postrelease and before/middle/after where needed.

See the ``setup.py`` of ``zest.releaser`` itself for some real world examples.

You'll have to make sure that the zest.releaser scripts know about your entry
points, for instance by placing your egg (with entry point) in the same
zc.recipe.egg section in your buildout as where you placed zest.releaser.  Or,
if you installed zest.releaser globally, your egg-with-entrypoint has to be
globally installed, too.


Comments about data dict items
------------------------------

Your entry point gets a data dictionary: the items you get in that dictionary
are documented below.  Some comments about them:

- Not all items are available.  If no history/changelog file is found, there
  won't be any ``data['history_lines']`` either.

- Items that are templates are normal python string templates.  They use
  dictionary replacement: they're actually passed the same data dict.  For
  instance, prerelease's ``data['commit_message']`` is by default ``Preparing
  release %(new_version)s``.  A "middle" entry point could modify this
  template to get a different commit message.



.. ### AUTOGENERATED FROM HERE ###

Prerelease data dict items
--------------------------

commit_msg
    Message template used when committing

history_file
    Filename of history/changelog file (when found)

history_header
    Header template used for 1st history header

history_lines
    List with all history file lines (when found)

name
    Name of the project being released

new_version
    New version (so 1.0 instead of 1.0dev)

original_version
    Version before prereleasing (e.g. 1.0dev)

today
    Date string used in history header

workingdir
    Original working directory

Release data dict items
-----------------------

name
    Name of the project being released

tag_already_exists
    Internal detail, don't touch this :-)

tagdir
    Directory where the tag checkout is placed (*if* a tag
    checkout has been made)

version
    Version we're releasing

workingdir
    Original working directory

Postrelease data dict items
---------------------------

commit_msg
    Message template used when committing

dev_version
    New development version with dev marker (so 1.1.dev0)

dev_version_template
    Template for dev version number

history_header
    Header template used for 1st history header

name
    Name of the project being released

new_version
    New development version (so 1.1)

nothing_changed_yet
    First line in new changelog section

workingdir
    Original working directory
