[Checkins] SVN: grok/branches/gotcha-configuration-actions/doc/upgrade.txt A document describing (incompatible) upgrades in Grok. Describes the changes

[Philipp von Weitershausen]

Log message for revision 81228:
  A document describing (incompatible) upgrades in Grok.  Describes the changes
  to grokkers, as well as the grok.define_permission -> grok.Permission change. 
  

Changed:
  A   grok/branches/gotcha-configuration-actions/doc/upgrade.txt

-=-
Added: grok/branches/gotcha-configuration-actions/doc/upgrade.txt
===================================================================
--- grok/branches/gotcha-configuration-actions/doc/upgrade.txt	                        (rev 0)
+++ grok/branches/gotcha-configuration-actions/doc/upgrade.txt	2007-10-30 19:47:57 UTC (rev 81228)
@@ -0,0 +1,83 @@
+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.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(
+        descriminator=('somecomponent', name),
+        callable=registerSomeComponent,
+        args=(name,)
+        )
+
+  The descriminator should be chosen so that registrations with the
+  same descriminator 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.


Property changes on: grok/branches/gotcha-configuration-actions/doc/upgrade.txt
___________________________________________________________________
Name: svn:eol-style
   + native