[Checkins] SVN: grok/trunk/doc/upgrade.txt Improve and expand the upgrade notes for Grok.

[Martijn Faassen]

Log message for revision 103918:
  Improve and expand the upgrade notes for Grok.
  

Changed:
  U   grok/trunk/doc/upgrade.txt

-=-
Modified: grok/trunk/doc/upgrade.txt
===================================================================
--- grok/trunk/doc/upgrade.txt	2009-09-14 12:46:39 UTC (rev 103917)
+++ grok/trunk/doc/upgrade.txt	2009-09-14 13:09:42 UTC (rev 103918)
@@ -35,23 +35,48 @@
   This change allows you to protect Grok views that come with the
   default permission by modifying your ``site.zcml``.
 
-* Grok buildout now creates a paster based project. To switch over
-  your projects to this approach, upgrade grokproject (``easy_install
-  -U grokproject``) first and create an empty project. Then examine
-  ``setup.py`` and ``buildout.cfg`` and copy over the files in ``etc``
-  (and adjust them).
+* When upgrading to a newer version of Grok, you should refer to the
+  newest list of versions as defined for this release of Grok.
 
-  Please note that ``parts/zopectl`` and ``parts/app`` will be deleted
-  when you re-run buildout. This means that ``parts/zopectl/access.log``
-  will be removed, and you may want to back up this file in advance.
+  For Grok 1.0b1, download the following file::
 
+    http://grok.zope.org/releaseinfo/grok-1.0b1.cfg
+
+  And replace ``versions.cfg`` in your project with this file.
+
+* There have been a lot of changes in grokproject and the project
+  layout it generates. This gives you a short description of how you
+  can upgrade your existing Grok project that was generated with an
+  older version of grokproject.
+
+  You should upgrade grokproject as follows::
+
+      $ easy_install -U grokproject
+
+  grokproject now creates a project based on `Paste Deploy`_, along
+  with a few other changes to the way various files are managed.
+
+  .. _`Paste Deploy`: http://pythonpaste.org/deploy/
+
+  To switch over your project to use a new layout, create a new, empty
+  project with grokproject and compare it with your current
+  layout. You can then compare it with your existing project layout
+  and make the appropriate changes to your project.
+
+  There have been changes to ``setup.py``, ``buildout.cfg`` and a new
+  ``etc`` directory has appeared.
+
   The templates for config files are now in ``etc`` - these get
-  generated by buildout into ``parts/etc``. Logfiles are now in
-  ``parts/log``.
+  generated by buildout into ``parts/etc``.  Find more information on
+  configuration and settings in ``etc/README.txt``.
 
-  Find more information on configuration and settings in
-  ``etc/README.txt``.
+  Log files are now placed in ``parts/log``.
 
+  Before re-running buildout to generate the new templates, please be
+  awware that ``parts/zopectl`` and ``parts/app`` will be deleted when
+  you re-run buildout. This means that ``parts/zopectl/access.log``
+  will be removed, and you may want to backup this file first.
+
   After making these adjustments, you can now run ``buildout`` for the
   project.
 
@@ -69,6 +94,17 @@
   Interpreter name has been changed from ``bin/python`` to
   ``bin/grokpy`` to avoid conflicts with virtualenv.
 
+* Old ``buildout.cfg`` contain a ``find-links`` line like this::
+
+   find-links = http://download.zope.org/distribution/
+
+  You should be able to safely remove this, as this points to a
+  repository of old releases that Grok doesn't depend on any more.
+
+  If you have problems after removing it and re-running ``bin/buildout``,
+  you can add it again however. We know that ``megrok.form`` for instance
+  depends on a release that was only available in this repository.
+
 .. _upgrade_notes_1.0a1:
 
 Upgrading to 1.0a1