Repair a Plone 3.1 buildout

Purpose

So you have a site running Plone 3.1.x and you need to re-run buildout for some reason.  You type 'bin/buildout' at the command-line prompt and start to notice some strange things happening.  You might see something like this in the output from buildout:

Getting distribution for 'plone.recipe.zope2instance'.
Got plone.recipe.zope2instance 4.0a1.
Getting distribution for 'Zope2>=2.12.1'.

 That might be followed by a bunch of errors you haven't seen before:

  File "build/bdist.macosx-10.6-i386/egg/Zope2/Startup/zopectl.py", line 313
    finally:
          ^
SyntaxError: invalid syntax

or

  File "/Users/cewing/virtualenvs/plone_dev/buildouts/test.buildout/eggs/tmpaBsXVw/mechanize-0.1.11-py2.4.egg/mechanize/_firefox3cookiejar.py", line 91
    yield row
SyntaxError: 'yield' not allowed in a 'try' block with a 'finally' clause

 or even:

UnknownExtra: zope.testbrowser 0.0 has no such extra feature 'zope_functional_testing'

Some folks have seen strange packages downloading like Products.CMFCore 2.2.0-alpha, which then introduce dependencies on Zope 2.12.  Whatever the symptom, the disease is the same.  You've got a broken buildout and need to get it fixed quickly.

Prerequisites

To follow this how-to, you'll need to have a basic understanding of how buildout works and a familiarity with the syntax of a buildout.cfg file. 

Step by step

Luckily, the fix to this problem is pretty simple.  Here's what you do:

1. Open your buildout.cfg file in a text editor.
2. in the main [buildout] section, add the following line:

   [buildout]
   parts =
       plone
   .
   .
   .
   
   # add this line here to add a section for pinning versions of packages and recipes.
   versions = versions

3. 
   
4. Then, after all the bits and pieces in the [buildout] section, but before your first part (perhaps [plone]), add the following:

   [versions]
   # Version pins for new style products go here
   plone.recipe.zope2instance = 3.6

5. Save your buildout.cfg file
6. re-run 'bin/buildout'
7. Bask in the glory of another problem solved.
   

Further information

This works because you have added a pin for plone.recipe.zope2instance to version 3.6.  A recently released version 4 of this buildout recipe introduced a dependency on Zope 2.12, which requires python 2.6 and will not work with Plone 3. 

The above procedure will work assuming that you are running vanilla Plone 3.1.x with no add-on packages.  If you do have add-ons, they may introduce dependencies that cause other problems.  Still, even in those cases the appropriate solution is to figure out what versions of installed packages work with your setup and add pins for those versions in the [versions] section as shown above.

One hint that can help you to figure this all out is to add a line like the following to the [buildout] section of your buildout.cfg file:

allow-picked-versions = false

 This tells buildout that you don't want it to pick _any_ versions on your behalf.  Every time the buildout process runs into a package that hasn't been pinned and needs to pick a version, it will fail with a message like the following:

While:
  Installing.
  Checking for upgrades.
  Getting distribution for 'zc.buildout'.
Error: Picked: zc.buildout = 1.4.2

For each time that this happens, you can review the available versions of the given package and pin the appropriate version in the [versions] section of your buildout.cfg file.  By doing this, you can build a KGS or Known Good Set of packages that will work with the add-on products you have installed.  You can keep the list to yourself, or you can upload the set to Good-Py, a lovely app created by Martin Aspeli and hosted on the Google App Engine.

To read more about this topic, you might want to check out this email thread:

http://plone.org/support/forums/core#nabble-td4024268|a4032703

You can read more about the Good-Py application in optilude's blog post about the project:

http://www.martinaspeli.net/articles/hello-good-py-a-known-good-versions-manager

There is a tool available for buildout that can help you to establish a list of the packages you use and the version numbers for each.  You might want to consider using it to create a complete list for your [versions] section:

http://pypi.python.org/pypi/buildout.dumppickedversions/0.4

You can read more about using buildout.dumppickedversions here and here.