[Checkins] SVN: groktoolkit/trunk/doc/ add upgrade notes for the forthcoming release

Thu Jan 20 11:33:59 EST 2011

Log message for revision 119793:
  add upgrade notes for the forthcoming release

Changed:
  U   groktoolkit/trunk/doc/developing_grok.rst
  U   groktoolkit/trunk/doc/upgrade.txt

-=-
Modified: groktoolkit/trunk/doc/developing_grok.rst
===================================================================

--- groktoolkit/trunk/doc/developing_grok.rst	2011-01-20 15:40:54 UTC (rev 119792)
+++ groktoolkit/trunk/doc/developing_grok.rst	2011-01-20 16:33:59 UTC (rev 119793)
@@ -51,7 +51,7 @@
 
    grok.zope.org:/var/www/html/grok/releaseinfo/[VERSION]/versions.cfg
 
-Manual post release steps
+Manual post-release steps
 ~~~~~~~~~~~~~~~~~~~~~~~~~
 
 After having released Grok, the following steps should be taken:

Modified: groktoolkit/trunk/doc/upgrade.txt
===================================================================
--- groktoolkit/trunk/doc/upgrade.txt	2011-01-20 15:40:54 UTC (rev 119792)
+++ groktoolkit/trunk/doc/upgrade.txt	2011-01-20 16:33:59 UTC (rev 119793)
@@ -12,6 +12,93 @@
 **Warning**. Please be sure to always backup your data (especially the
 ``Data.fs`` file) before you perform upgrades.
 
+.. _upgrade_notes_1.3:
+
+Upgrading to 1.3 (2011-01-20)
+-----------------------------
+
+To upgrade your Grok based project, make sure your project's ``buildout.cfg``
+extends from the ``versions.cfg`` of the latest Grok Toolkit release. This file
+can be found here::
+
+    http://grok.zope.org/releaseinfo/1.3/versions.cfg
+
+Then re-run ``bootstrap.py`` in your project to prevent potential
+``zc.buildout`` version conflicts. Then run ``bin/buildout`` to get the latest
+versions of all of the packages that comprise the Grok Toolkit.
+
+Extra notes:
+
+- For newly created projects using the grokproject tool, z3c.testsetup has
+  been removed in favor of manual registration of tests. Even though tests
+  discovery and registration through ``z3c.testsetup`` should still work for
+  existing projects, it is advisable to start registering tests "manually".
+  More documentation concerning this topic is forthcoming. See also the
+  ``tests.py`` module generated by the ``grokproject`` tool for examples.
+
+- The 'static' directory is no longer automatically grokked and registered as a
+  ``DirectoryResource`` for serving static resources. Serving static resources
+  is being superseded by the `Fanstatic`_ library and WSGI components.
+
+  Newly created project using the ``grokproject`` tool will have the
+  infrastructure set up for serving static resources, and a compatibility layer
+  has been created through `zope.fanstatic`_. This compatibility layer will
+  allow for computing URLs to resources in Zope Page Templates and in view code.
+
+  The compatibility layer will also set the ``base_url`` necessary for the
+  Fanstatic WSGI components to automatically inject resource inclusions in the
+  ``<head>`` section of the rendered HMTL, and for serving the resources.
+  Having the Fanstatic WSGI components serve the static resources will off-load
+  this task from Grok, generally improving the application's performance.
+
+  In order to update your current Grok project to the most recent Grok Toolkit
+  release, you need to register a Fanstatic ``Library`` for each of the
+  `static` directories your project may have. Registering the 'static'
+  directory involves three steps:
+
+  1) Add `zope.fanstatic` and `fanstatic` to the `install_requires` in your
+     project's ``setup.py``. If you are using z3c.autoinclude in your
+     ``configure.zcml``, the necessary component registrations in
+     ``zope.fanstatic`` will be done automatically.
+
+     If you do not use ``z3c.autoinclude``, include ``zope.fanstatic`` in your
+     ``configure.zcml``.
+
+  2) Include the following code in ``resource.py``::
+
+     from fanstatic import Library
+     library = Library(PACKAGENAME, 'static')
+
+  3) In the ``setup.py`` of your project, add the following entry point (again,
+     for each 'static' directory your project may have) ::
+
+     'fanstatic.libraries': [
+         'PACKAGENAME = PACKAGENAME.resource:library'
+     ]
+
+  Where the ``PACKAGENAME`` should be replaced with the dotted package name in
+  which the 'static' directory resides.
+
+  The ``grok.DirectoryResource`` components have not been removed from Grok.
+  So, your directory resources should continue to work unchanged.
+
+- The way templates are associated to view components has changed. In general,
+  this should not lead to problems, just less spurious warnings when starting
+  your Grok application.
+
+- The default views that were rendered in case of application errors (like for
+  ``NotFound`` exceptions, or ``Unauthorized`` exceptions used to be done
+  through the now deprecated ``zope.app.http`` and ``zope.app.exception``
+  packages. These packages have been replaced by the ``zope.errorview`` package.
+
+  In case your application imports from the aformentiond deprecated package,
+  you should either include these packages in the ``install_requires`` section
+  in your project's ``setup.py`` or port the code to use ``zope.errorview`` -
+  the later is the recommend practice.
+
+.. _`Fanstatic`: http://fanstatic.org/
+.. _`zope.fanstatic`: http://pypi.python.org/pypi/zope.fanstatic/
+
 .. _upgrade_notes_1.2:
 
 Upgrading to 1.2 (2010-10-26)

