Upgrade notes
=============

This document outlines how to update Grok applications so that they
continue to work with newer versions of Grok.  This document only
describes changes involving incompatibilities or deprecations, not new
features (please refer to ``CHANGES.txt`` for those).

Upgrading to 0.12
-----------------

* Please upgrade grokproject::

    $ easy_install -U grokproject

* If you have existing Grok projects and you want to make use of 
  Grok's new autoinclusion functionality in them, you can place
  the following line in your project's ``configure.zcml``:

    <includeDependencies package="." />

  This will cause the ZCML for ``setup.py`` dependencies of your
  package to be loaded automatically. You can now get rid of any
  manual ``include`` statements (except the one that includes ``grok``
  itself).

  For new projects created by ``grokproject``, this line will be
  automatically be added for you and you don't have to do anything except
  to upgrade ``grokproject``::

    $ easy_install -U grokproject

* The convention that classes ending with -Base automatically become base
  classes has been removed with martian 0.9.4. Please add the grok.baseclass()
  directive to these classes explicitly where the 'Base' class convention was
  relied upon to preserve existing functionality.


Upgrading to 0.11
-----------------

* ``grok.define_permission`` has been removed in favour of a
  ``grok.Permission`` base class, for reasons of symmetry.  Instead of
  writing::

    grok.define_permission('myapp.ViewCavePainting')

  you should now write::

    class View(grok.Permission):
        grok.name('myapp.ViewCavePainting')

  If you also want to supply a title and description for the
  permission, use the ``grok.title()`` and ``grok.description()``
  directives on the class.

* ``grok.grok`` and ``grok.grok_component`` have been deprecated.  If
  you need them for tests (which is their only legimitate use), you
  should import them both from ``grok.testing``.

* Grokkers should now emit configuration actions instead of
  registering components right away.  For that they now get a new
  keyword argument called ``config``, the configuration context.  For
  example, a grokker that used to do this::

    registerSomeComponent(foo, name)

  should now be doing this::

    config.action(
        discriminator=('somecomponent', name),
        callable=registerSomeComponent,
        args=(name,)
        )

  The discriminator should be chosen so that registrations with the
  same discriminator conflict (in the above example, if somebody tried
  to register two different components under the same name, you'd get
  a conflict).

* Grokkers no longer get the ``context`` and ``templates`` keyword
  arguments.  If they need access to these values, they can now get
  them as module annotations from the ``module_info`` object like
  this::

      context = module_info.getAnnotation('grok.context')
      templates = module_info.getAnnotation('grok.templates')

* Note that grokkers must always take arbitrary keyword arguments
  (``**kw``), as specified by the ``martian.interfaces.IGrokker``
  interface.  A minimal specification of the ``grok()`` method is
  therefore::

    def grok(self, name, obj, **kw):
        ...

  though grokkers will likely want to take ``module_info`` as well as
  ``config`` explicitly::

    def grok(self, name, obj, module_info, config, **kw):
        ...

  If your application defines custom grokkers and you're getting a
  ``TypeError`` about unexpected arguments to ``grok``, you likely
  need to update the signature of the ``grok()`` method like described
  above.


Upgrading to 0.10
-----------------

There were no incompatible changes.
