[Checkins] SVN: grok/trunk/doc/ add upgrade notes to index page of official documentation, this reduces the number of manual post release steps
Jan-Wijbrand Kolman
janwijbrand at gmail.com
Tue Oct 26 08:29:37 EDT 2010
Log message for revision 117887:
add upgrade notes to index page of official documentation, this reduces the number of manual post release steps
Changed:
U grok/trunk/doc/contents.rst
U grok/trunk/doc/developing_grok.rst
U grok/trunk/doc/docindex.template
U grok/trunk/doc/upgrade.txt
-=-
Modified: grok/trunk/doc/contents.rst
===================================================================
--- grok/trunk/doc/contents.rst 2010-10-26 11:37:24 UTC (rev 117886)
+++ grok/trunk/doc/contents.rst 2010-10-26 12:29:36 UTC (rev 117887)
@@ -6,6 +6,7 @@
:maxdepth: 2
changes.rst
+ upgrade.rst
tutorial.rst
grok_overview.rst
reference/index.rst
Modified: grok/trunk/doc/developing_grok.rst
===================================================================
--- grok/trunk/doc/developing_grok.rst 2010-10-26 11:37:24 UTC (rev 117886)
+++ grok/trunk/doc/developing_grok.rst 2010-10-26 12:29:36 UTC (rev 117887)
@@ -71,20 +71,20 @@
.. _`releases folder`: http://grok.zope.org/project/releases/
-3. Update the `upgrade notes`_ with the latest version as in
- ``doc/upgrade.txt``.
+3. Official Documentation: Create a build of the docs from the tagged
+ release and copy it to the server. Detailed steps are documented in the
+ `Updating the Official Grok Documentation (OGD)`_ page.
- .. _`upgrade notes`: http://grok.zope.org/project/upgrade-notes
-
4. Create a news item in the `blog folder`_ announcing the news. The text
can be based on the release notes written at point 7.
.. _`blog folder`: http://grok.zope.org/blog/
5. Make both the new release notes, the new news item, as well as the
- updated upgrade notes public. 6. Update the sidebar in the site. You can
- edit it here::
+ updated upgrade notes public.
+6. Update the sidebar in the site. You can edit it here::
+
http://grok.zope.org/portal_skins/custom/portlet_download/manage_main
7. Community Documentation: Update the Plone Help Center used for Grok
@@ -95,15 +95,11 @@
documentation which is truly outdated and no longer best practice. Do this
here: http://grok.zope.org/documentation/edit
-9. Official Documentation: Create a build of the docs from the tagged
- release and copy it to the server. Detailed steps are documented in the
- `Updating the Official Grok Documentation (OGD)`_ page.
-
-10. Send out an email to at least zope-announce at zope.org as well as grok-
+8. Send out an email to at least zope-announce at zope.org as well as grok-
dev at zope.org announcing the new release. The text can be based on the
release notes written at point 7.
-11. Update the Grok Wikipedia article with the information about the latest
+9. Update the Grok Wikipedia article with the information about the latest
release: http://en.wikipedia.org/wiki/Grok_(web_framework)
.. _`Updating the Official Grok Documentation (OGD)`: http://grok.zope.org/project/meta/updating-the-official-grok-documentation-ogd
Modified: grok/trunk/doc/docindex.template
===================================================================
--- grok/trunk/doc/docindex.template 2010-10-26 11:37:24 UTC (rev 117886)
+++ grok/trunk/doc/docindex.template 2010-10-26 12:29:36 UTC (rev 117887)
@@ -15,20 +15,24 @@
>Grok Tutorial</a><br>
<span class="linkdescr">Get started with Grok.</span></p>
+ <p class="biglink"><a class="biglink" href="{{ pathto("reference/index") }}">The Grok Reference</a><br>
+ <span class="linkdescr">Describes syntax and package elements.</span></p>
+
<p class="biglink"><a class="biglink" href="{{ pathto("grok_overview") }}"
>Grok Developer Notes</a><br>
<span class="linkdescr">Overview of what's in Grok and how to use it.</span></p>
- <p class="biglink"><a class="biglink" href="{{ pathto("reference/index") }}">The Grok Reference</a><br>
- <span class="linkdescr">Describes syntax and package elements.</span></p>
+ <p class="biglink"><a class="biglink" href="{{ pathto("naming_conventions") }}">Naming Conventions</a><br>
+ <span class="linkdescr">How to name your stuff correctly.</span></p>
</td><td width="50%">
<p class="biglink"><a class="biglink" href="{{ pathto("changes") }}"
>What's new in Grok?</a><br>
<span class="linkdescr">Changes made in each Grok release.</span></p>
- <p class="biglink"><a class="biglink" href="{{ pathto("naming_conventions") }}">Naming Conventions</a><br>
- <span class="linkdescr">How to name your stuff correctly.</span></p>
+ <p class="biglink"><a class="biglink" href="{{ pathto("upgrade") }}"
+ >Upgrading notes</a><br>
+ <span class="linkdescr">How to upgrade your project to a new version of the Grok Toolkit.</span></p>
<p class="biglink"><a class="biglink" href="{{ pathto("developing_grok") }}">Developing Grok</a><br>
<span class="linkdescr">Notes for developers <strong>of</strong> Grok.</span></p>
Modified: grok/trunk/doc/upgrade.txt
===================================================================
--- grok/trunk/doc/upgrade.txt 2010-10-26 11:37:24 UTC (rev 117886)
+++ grok/trunk/doc/upgrade.txt 2010-10-26 12:29:36 UTC (rev 117887)
@@ -1,35 +1,82 @@
.. _upgrade_notes:
+
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).
+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).
**Warning**. Please be sure to always backup your data (especially the
``Data.fs`` file) before you perform upgrades.
.. _upgrade_notes_1.2:
-Upgrading to 1.2 (unreleased)
+Upgrading to 1.2 (2010-10-26)
-* make sure your project's buildout.cfg now refers to
+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.2/versions.cfg
- then re-run ``bootstrap.py`` to prevent potential zc.buldout version
- conflicts. then run bin/buildout.
+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.
-* zdaemon support has been removed, use a fresh app skeleton as an example
- how to restructure you app.
+Extra notes:
-* zope.app.* dependencies removed, install_require yourself now
+* In Grok 1.2 the "zdaemon" support has been removed. If your project still
+ relied on this method of starting and stopping the server you will need to
+ update your prokject.
-* a configuration of a package might not be triggered implicitely anymore,
- include it your self in the configure.zcml
+ The easiest way for find what parts and file to add, is to create a new
+ project using the ``grokproject`` tool and then to compare its structure to
+ your project's structure. Look for the "debug_ini" and "deploy_ini" parts in
+ the ``buildout.cfg`` file and the corresponding configuration file templates.
+* A large numner of ``zope.app.`` dependencies have been removed. Even though
+ most of these packages just contained backwards compatibility imports, your
+ application might still contain imports from these ``zope.app.`` packages.
+
+ The best way to update this, is to carefully search for ``zope.app.`` imports
+ in your project and to rewrite them to the new import locations. Note though,
+ that in rare cases, this might break persisted object in your database.
+
+ If this is the case, you will need to add the particular ``zope.app.``
+ package to the ``install_requires`` section in the ``setup.py`` of your
+ project. After a re-run of ``./bin/buildout`` these package are now again
+ available to your project.
+
+ In general it is good practice to explicitely list the dependencies of your
+ project in the ``setup.py``. In other words: if your project imports from
+ packages, these packages should be listed in the ``install_requires`` of your
+ project's ``setup.py``.
+
+* One specific case of a ``zope.app.`` depdendency that got removed and
+ replaced is ``zope.app.testing`` that is used in the test setup of your
+ project. Most of the functionality in ``zope.app.testing`` has been rebuild
+ in ``zope.component.testlayer``, ``zope.app.appsetup``, and
+ ``zope.app.wsgi.testlayer``.
+
+ Again, the easiest way to upgrade this part of your project, is to look a
+ freshly created project using the ``grokproject`` tool. There, the test setup
+ code uses the "new style" test layers for functional testing.
+
+* In some case the configuration step of a dependency is not triggered
+ anymore, where it used to be before most of the ``zope.app.`` dependencies
+ got removed. If this is the case (for example for components in in
+ zope.pluggableauth.plugins), you will need to trigger the configuration
+ yourself from your project's ``configure.zcml`` like so::
+
+ <include package="[PACKAGE_TO_CONFIGURE]" />
+
+ or, for a specific ``*.zcml`` file in package::
+
+ <include package="[PACKAGE_TO_CONFIGURE]" file="[ZCML_FILE]"/>
+
.. _upgrade_notes_1.1:
Upgrading to 1.1 (2010-05-18)
More information about the checkins
mailing list