diff -r 5ff1fc726848 -r c6bca38c1cbf eggs/zc.buildout-1.5.2-py2.6.egg/zc/buildout/update.txt
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/eggs/zc.buildout-1.5.2-py2.6.egg/zc/buildout/update.txt	Sat Jan 08 11:20:57 2011 +0530
@@ -0,0 +1,263 @@
+Automatic Buildout Updates
+==========================
+
+When a buildout is run, one of the first steps performed is to check
+for updates to either zc.buildout or setuptools.  To demonstrate this,
+we've created some "new releases" of buildout and setuptools in a
+new_releases folder:
+
+    >>> ls(new_releases)
+    d  setuptools
+    -  setuptools-99.99-py2.4.egg
+    d  zc.buildout
+    -  zc.buildout-100.0b1-pyN.N.egg
+    -  zc.buildout-99.99-py2.4.egg
+
+Let's update the sample buildout.cfg to look in this area:
+
+    >>> write(sample_buildout, 'buildout.cfg',
+    ... """
+    ... [buildout]
+    ... find-links = %(new_releases)s
+    ... index = %(new_releases)s
+    ... parts = show-versions
+    ... develop = showversions
+    ...
+    ... [show-versions]
+    ... recipe = showversions
+    ... """ % dict(new_releases=new_releases))
+
+We'll also include a recipe that echos the versions of setuptools and
+zc.buildout used:
+
+    >>> mkdir(sample_buildout, 'showversions')
+
+    >>> write(sample_buildout, 'showversions', 'showversions.py',
+    ... """
+    ... import pkg_resources
+    ...
+    ... class Recipe:
+    ...
+    ...     def __init__(self, buildout, name, options):
+    ...         pass
+    ...
+    ...     def install(self):
+    ...         for project in 'zc.buildout', 'setuptools':
+    ...             req = pkg_resources.Requirement.parse(project)
+    ...             print project, pkg_resources.working_set.find(req).version
+    ...         return ()
+    ...     update = install
+    ... """)
+
+
+    >>> write(sample_buildout, 'showversions', 'setup.py',
+    ... """
+    ... from setuptools import setup
+    ...
+    ... setup(
+    ...     name = "showversions",
+    ...     entry_points = {'zc.buildout': ['default = showversions:Recipe']},
+    ...     )
+    ... """)
+
+
+Now if we run the buildout, the buildout will upgrade itself to the
+new versions found in new releases:
+
+    >>> print system(buildout),
+    Getting distribution for 'zc.buildout'.
+    Got zc.buildout 99.99.
+    Getting distribution for 'setuptools'.
+    Got setuptools 99.99.
+    Upgraded:
+      zc.buildout version 99.99,
+      setuptools version 99.99;
+    restarting.
+    Generated script '/sample-buildout/bin/buildout'.
+    Develop: '/sample-buildout/showversions'
+    Installing show-versions.
+    zc.buildout 99.99
+    setuptools 99.99
+
+Notice that, even though we have a newer beta version of zc.buildout
+available, the final "99.99" was selected.  If you want to get non-final
+versions, specify a specific version in your buildout's versions
+section, you typically want to use the --accept-buildout-test-releases
+option to the bootstrap script, which internally uses the
+``accept-buildout-test-releases = true`` discussed below.
+
+Our buildout script's site.py has been updated to use the new eggs:
+
+    >>> cat(sample_buildout, 'parts', 'buildout', 'site.py')
+    ... # doctest: +NORMALIZE_WHITESPACE +ELLIPSIS
+    "...
+    def addsitepackages(known_paths):
+        """Add site packages, as determined by zc.buildout.
+    <BLANKLINE>
+        See original_addsitepackages, below, for the original version."""
+        setuptools_path = '/sample-buildout/eggs/setuptools-99.99-pyN.N.egg'
+        sys.path.append(setuptools_path)
+        known_paths.add(os.path.normcase(setuptools_path))
+        import pkg_resources
+        buildout_paths = [
+            '/sample-buildout/eggs/zc.buildout-99.99-pyN.N.egg',
+            '/sample-buildout/eggs/setuptools-99.99-pyN.N.egg'
+            ]
+        for path in buildout_paths:
+            sitedir, sitedircase = makepath(path)
+            if not sitedircase in known_paths and os.path.exists(sitedir):
+                sys.path.append(sitedir)
+                known_paths.add(sitedircase)
+                pkg_resources.working_set.add_entry(sitedir)
+        sys.__egginsert = len(buildout_paths) # Support setuptools.
+        original_paths = [
+            ...
+            ]
+        for path in original_paths:
+            if path == setuptools_path or path not in known_paths:
+                addsitedir(path, known_paths)
+        return known_paths
+    ...
+
+Now, let's recreate the sample buildout. If we specify constraints on
+the versions of zc.buildout and setuptools (or distribute) to use,
+running the buildout will install earlier versions of these packages:
+
+    >>> write(sample_buildout, 'buildout.cfg',
+    ... """
+    ... [buildout]
+    ... find-links = %(new_releases)s
+    ... index = %(new_releases)s
+    ... parts = show-versions
+    ... develop = showversions
+    ... zc.buildout-version = < 99
+    ... setuptools-version = < 99
+    ... distribute-version = < 99
+    ...
+    ... [show-versions]
+    ... recipe = showversions
+    ... """ % dict(new_releases=new_releases))
+
+Now we can see that we actually "upgrade" to an earlier version.
+
+    >>> print system(buildout),
+    Upgraded:
+      zc.buildout version 1.0.0,
+      setuptools version 0.6;
+    restarting.
+    Develop: '/sample-buildout/showversions'
+    Updating show-versions.
+    zc.buildout 1.0.0
+    setuptools 0.6
+
+There are a number of cases, described below, in which the updates
+don't happen.
+
+We won't upgrade in offline mode:
+
+    >>> write(sample_buildout, 'buildout.cfg',
+    ... """
+    ... [buildout]
+    ... find-links = %(new_releases)s
+    ... index = %(new_releases)s
+    ... parts = show-versions
+    ... develop = showversions
+    ...
+    ... [show-versions]
+    ... recipe = showversions
+    ... """ % dict(new_releases=new_releases))
+
+    >>> print system(buildout+' -o'),
+    Develop: '/sample-buildout/showversions'
+    Updating show-versions.
+    zc.buildout 1.0.0
+    setuptools 0.6
+
+Or in non-newest mode:
+
+    >>> print system(buildout+' -N'),
+    Develop: '/sample-buildout/showversions'
+    Updating show-versions.
+    zc.buildout 1.0.0
+    setuptools 0.6
+
+We also won't upgrade if the buildout script being run isn't in the
+buildout's bin directory.  To see this we'll create a new buildout
+directory:
+
+    >>> sample_buildout2 = tmpdir('sample_buildout2')
+    >>> write(sample_buildout2, 'buildout.cfg',
+    ... """
+    ... [buildout]
+    ... find-links = %(new_releases)s
+    ... index = %(new_releases)s
+    ... parts =
+    ... """ % dict(new_releases=new_releases))
+
+    >>> cd(sample_buildout2)
+    >>> print system(buildout),
+    Creating directory '/sample_buildout2/bin'.
+    Creating directory '/sample_buildout2/parts'.
+    Creating directory '/sample_buildout2/eggs'.
+    Creating directory '/sample_buildout2/develop-eggs'.
+    Getting distribution for 'zc.buildout'.
+    Got zc.buildout 99.99.
+    Getting distribution for 'setuptools'.
+    Got setuptools 99.99.
+    Not upgrading because not running a local buildout command.
+
+    >>> ls('bin')
+
+As mentioned above, the ``accept-buildout-test-releases = true`` means that
+newer non-final versions of these dependencies are preferred.  Typically
+users are not expected to actually manipulate this value.  Instead, the
+bootstrap script creates a buildout buildout script that passes in the
+value as a command line override. This then results in the buildout
+script being rewritten to remember the decision.
+
+We'll mimic this by passing the argument actually in the command line.
+
+    >>> cd(sample_buildout)
+    >>> write(sample_buildout, 'buildout.cfg',
+    ... """
+    ... [buildout]
+    ... find-links = %(new_releases)s
+    ... index = %(new_releases)s
+    ... parts = show-versions
+    ... develop = showversions
+    ...
+    ... [show-versions]
+    ... recipe = showversions
+    ... """ % dict(new_releases=new_releases))
+
+    >>> print system(buildout +
+    ...              ' buildout:accept-buildout-test-releases=true'),
+    ... # doctest: +NORMALIZE_WHITESPACE
+    Getting distribution for 'zc.buildout'.
+    Got zc.buildout 100.0b1.
+    Upgraded:
+      zc.buildout version 100.0b1,
+      setuptools version 99.99;
+    restarting.
+    Generated script '/sample-buildout/bin/buildout'.
+    NOTE: Accepting early releases of build system packages.  Rerun bootstrap
+          without --accept-buildout-test-releases (-t) to return to default
+          behavior.
+    Develop: '/sample-buildout/showversions'
+    Updating show-versions.
+    zc.buildout 100.0b1
+    setuptools 99.99
+
+The buildout script shows the change.
+
+    >>> buildout_script = join(sample_buildout, 'bin', 'buildout')
+    >>> import sys
+    >>> if sys.platform.startswith('win'):
+    ...     buildout_script += '-script.py'
+    >>> print open(buildout_script).read() # doctest: +ELLIPSIS
+    #...
+    sys.argv.insert(1, 'buildout:accept-buildout-test-releases=true')
+    print ('NOTE: Accepting early releases of build system packages.  Rerun '
+           'bootstrap without --accept-buildout-test-releases (-t) to return to '
+           'default behavior.')
+    ...