merge lp:~gary/zc.buildout/betafix8. merges trunk and simplifies the pattern...

merge lp:~gary/zc.buildout/betafix8.  merges trunk and simplifies the pattern for using newer versions of buildout, per review.

CHANGES.txt

@@ -9,17 +9,23 @@ New features:
 - zc.buildout supports Python 2.7.
 
 - By default, Buildout and the bootstrap script now prefer final versions of
-  Buildout, recipes, and extensions.  This can be changed by setting
-  ``prefer-final-build-system = false`` in your configuration's
-  [buildout] section, and by using the --accept-early-release flag when
-  calling bootstrap.  This will hopefully allow beta releases to be more
-  easily and safely made in the future.  Note that dependencies of your
-  software do not have this behavior: use the pre-existing switch
-  ``prefer-final = true`` to get this behavior.
+  Buildout, recipes, and extensions.  This can be changed by using the
+  --accept-buildout-test-releases flag (or -t for short) when calling
+  bootstrap.  This will hopefully allow beta releases of these items to
+  be more easily and safely made in the future.
+
+  NOTE: dependencies of your own software are not affected by this new
+  behavior. Buildout continues to choose the newest available versions
+  of your dependencies regardless of whether they are final releases. To
+  prevent this, use the pre-existing switch ``prefer-final = true`` in
+  the [buildout] section of your configuration file (see
+  http://pypi.python.org/pypi/zc.buildout#preferring-final-releases) or
+  pin your versions using a versions section (see
+  http://pypi.python.org/pypi/zc.buildout#repeatable-buildouts-controlling-eggs-used).
 
 Bugs fixed:
 
-- You can now again use virtualenv with zc.buildout.  The new features to let
+- You can now again use virtualenv with Buildout.  The new features to let
   buildout be used with a system Python are disabled in this configuration,
   and the previous script generation behavior (1.4.3) is used, even if
   the new function ``zc.buildout.easy_install.sitepackage_safe_scripts``
@@ -77,6 +83,10 @@ New Features:
   * The buildout script generated by bootstrap honors more of the settings
     in the designated configuration file (e.g., buildout.cfg).
 
+  * Correctly handle systems where pkg_resources is present but the rest of
+    setuptools is missing (like Ubuntu installs).
+    https://bugs.launchpad.net/zc.buildout/+bug/410528
+
 - You can develop zc.buildout using Distribute instead of Setuptools.  Use
   the --distribute option on the dev.py script.  (Releases should be tested
   with both Distribute and Setuptools.)  The tests for zc.buildout pass
@@ -532,7 +542,7 @@ Bugs Fixed
 - 92891: bootstrap crashes with recipe option in buildout section.
 
 - 113085: Buildout exited with a zero exist status when internal errors
-  occured.
+  occurred.
 
 
 1.0.0b23 (2007-03-19)

bootstrap/bootstrap.py

@@ -16,8 +16,6 @@
 Simply run this script in a directory containing a buildout.cfg.
 The script accepts buildout command-line options, so you can
 use the -c option to specify an alternate configuration file.
-
-$Id$
 """
 
 import os, shutil, sys, tempfile, textwrap, urllib, urllib2, subprocess
@@ -121,17 +119,15 @@ parser.add_option("--eggs",
                   help=("Specify a directory for storing eggs.  Defaults to "
                         "a temporary directory that is deleted when the "
                         "bootstrap script completes."))
-parser.add_option("--accept-early-release", dest='accept_early_release',
+parser.add_option("-t", "--accept-buildout-test-releases",
+                  dest='accept_buildout_test_releases',
                   action="store_true", default=False,
                   help=("Normally, if you do not specify a --version, the "
-                        "bootstrap script gets the newest *final* versions "
-                        "of zc.buildout for you.  If you use this flag, "
-                        "bootstrap will get the newest releases even if they "
-                        "are alphas or betas.  Note that, if you do want to "
-                        "use early buildout releases, you probably want "
-                        "to also set ``prefer-final-build-system= false`` "
-                        "in the [buildout] section of your configuration "
-                        "file."))
+                        "bootstrap script and buildout gets the newest "
+                        "*final* versions of zc.buildout and its recipes and "
+                        "extensions for you.  If you use this flag, "
+                        "bootstrap and buildout will get the newest releases "
+                        "even if they are alphas or betas."))
 parser.add_option("-c", None, action="store", dest="config_file",
                    help=("Specify the path to the buildout configuration "
                          "file to be used."))
@@ -153,16 +149,15 @@ if options.setup_source is None:
     else:
         options.setup_source = setuptools_source
 
-args = args + ['bootstrap']
-
+if options.accept_buildout_test_releases:
+    args.append('buildout:accept-buildout-test-releases=true')
+args.append('bootstrap')
 
 try:
-    to_reload = False
     import pkg_resources
-    to_reload = True
+    import setuptools # A flag.  Sometimes pkg_resources is installed alone.
     if not hasattr(pkg_resources, '_distribute'):
         raise ImportError
-    import setuptools # A flag.  Sometimes pkg_resources is installed alone.
 except ImportError:
     ez_code = urllib2.urlopen(
         options.setup_source).read().replace('\r\n', '\n')
@@ -174,10 +169,8 @@ except ImportError:
     if options.use_distribute:
         setup_args['no_fake'] = True
     ez['use_setuptools'](**setup_args)
-    if to_reload:
-        reload(pkg_resources)
-    else:
-        import pkg_resources
+    reload(sys.modules['pkg_resources'])
+    import pkg_resources
     # This does not (always?) update the default working set.  We will
     # do it.
     for path in sys.path:
@@ -212,7 +205,7 @@ env = dict(
 
 requirement = 'zc.buildout'
 version = options.version
-if version is None and not options.accept_early_release:
+if version is None and not options.accept_buildout_test_releases:
     # Figure out the most recent final version of zc.buildout.
     import setuptools.package_index
     _final_parts = '*final-', '*final'
@@ -252,7 +245,7 @@ else: # Windows prefers this, apparently; otherwise we would prefer subprocess
 if exitcode != 0:
     sys.stdout.flush()
     sys.stderr.flush()
-    print ("An error occured when trying to install zc.buildout. "
+    print ("An error occurred when trying to install zc.buildout. "
            "Look above this message for any errors that "
            "were output by easy_install.")
     sys.exit(exitcode)

src/zc/buildout/bootstrap.txt

@@ -93,23 +93,14 @@ If you want to accept early releases of zc.buildout, you either need to
 specify an explicit version (using --version here and specifying the
 version in the buildout configuration file using the
 ``buildout-version`` option or the ``versions`` option) or specify that you
-accept early releases.
-
-You accept early releases by using ``--accept-early-release`` on the
-bootstrap script and specifying ``prefer-final-build-system = false`` in the
-buildout configuration file.  You must do both.
+accept early releases by using ``--accept-buildout-test-releases`` on the
+bootstrap script.
 
 Here's an example.
 
-    >>> write('buildout.cfg',
-    ... '''
-    ... [buildout]
-    ... parts =
-    ... prefer-final-build-system = false
-    ... ''')
     >>> ignored = system(
     ...     zc.buildout.easy_install._safe_arg(sys.executable)+' '+
-    ...     'bootstrap.py --accept-early-release')
+    ...     'bootstrap.py --accept-buildout-test-releases')
     >>> print open(buildout_site_py).read() # doctest: +ELLIPSIS
     "...
         buildout_paths = [
@@ -120,13 +111,41 @@ Here's an example.
 
 Notice we are now using zc.buildout 100.0b1, a non-final release.
 
-Now we'll go back to the default of preferring final versions.
+The buildout script remembers the decision to accept early releases, and
+alerts the user.
 
-    >>> write('buildout.cfg',
-    ... '''
-    ... [buildout]
-    ... parts =
-    ... ''')
+    >>> print system(join('bin', 'buildout')),
+    ... # doctest: +NORMALIZE_WHITESPACE
+    NOTE: Accepting early releases of build system packages.  Rerun bootstrap
+          without --accept-buildout-test-releases (-t) to return to default
+          behavior.
+
+This is accomplished within the script itself.
+
+    >>> 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.')
+    ...
+
+As the note says, to undo, you just need to re-run bootstrap without
+--accept-buildout-test-releases.
+
+    >>> ignored = system(
+    ...     zc.buildout.easy_install._safe_arg(sys.executable)+' '+
+    ...     'bootstrap.py')
+    >>> print open(buildout_site_py).read() # doctest: +ELLIPSIS
+    "...
+        buildout_paths = [
+            '/sample/eggs/setuptools-...egg',
+            '/sample/eggs/zc.buildout-99.99-pyN.N.egg'
+            ]
+    ...
+    >>> ('buildout:accept-buildout-test-releases=true' in
+    ... open(buildout_script).read())
+    False
 
 Now we will try the `--version` option, which lets you define a version for
 `zc.buildout`. If not provided, bootstrap will look for the latest one.
@@ -329,14 +348,12 @@ Here's the entire help text.
       --eggs=EGGS           Specify a directory for storing eggs.  Defaults to a
                             temporary directory that is deleted when the bootstrap
                             script completes.
-      --accept-early-release
+      -t, --accept-buildout-test-releases
                             Normally, if you do not specify a --version, the
-                            bootstrap script gets the newest *final* versions of
-                            zc.buildout for you.  If you use this flag, bootstrap
+                            bootstrap script and buildout gets the newest *final*
+                            versions of zc.buildout and its recipes and extensions
+                            for you.  If you use this flag, bootstrap and buildout
                             will get the newest releases even if they are alphas
-                            or betas.  Note that, if you do want to use early
-                            buildout releases, you probably want to also set
-                            ``prefer-final-build-system= false`` in the [buildout]
-                            section of your configuration file.
+                            or betas.
       -c CONFIG_FILE        Specify the path to the buildout configuration file to
                             be used.

src/zc/buildout/buildout.py

@@ -116,6 +116,7 @@ def _unannotate(data):
     return data
 
 _buildout_default_options = _annotate_section({
+    'accept-buildout-test-releases': 'false',
     'allow-hosts': '*',
     'allow-picked-versions': 'true',
     'bin-directory': 'bin',
@@ -131,7 +132,6 @@ _buildout_default_options = _annotate_section({
     'offline': 'false',
     'parts-directory': 'parts',
     'prefer-final': 'false',
-    'prefer-final-build-system': 'true',
     'python': 'buildout',
     'relative-paths': 'false',
     'socket-timeout': '',
@@ -235,8 +235,8 @@ class Buildout(UserDict.DictMixin):
         self._logger = logging.getLogger('zc.buildout')
         self.offline = (buildout_section['offline'] == 'true')
         self.newest = (buildout_section['newest'] == 'true')
-        self.prefer_final_build_system = (
-            buildout_section['prefer-final-build-system'] == 'true')
+        self.accept_buildout_test_releases = (
+            buildout_section['accept-buildout-test-releases'] == 'true')
 
         ##################################################################
         ## WARNING!!!
@@ -281,8 +281,8 @@ class Buildout(UserDict.DictMixin):
         self.newest = options.get_bool('newest')
         zc.buildout.easy_install.prefer_final(
             options.get_bool('prefer-final'))
-        self.prefer_final_build_system = options.get_bool(
-            'prefer-final-build-system')
+        self.accept_buildout_test_releases = options.get_bool(
+            'accept-buildout-test-releases')
         zc.buildout.easy_install.use_dependency_links(
             options.get_bool('use-dependency-links'))
         zc.buildout.easy_install.allow_picked_versions(
@@ -338,7 +338,7 @@ class Buildout(UserDict.DictMixin):
                 [options['develop-eggs-directory'],
                  options['eggs-directory']],
                 include_site_packages=_sys_executable_has_broken_dash_S,
-                prefer_final = self.prefer_final_build_system,
+                prefer_final=not self.accept_buildout_test_releases,
                 )
         else:
             ws = zc.buildout.easy_install.install(
@@ -350,7 +350,7 @@ class Buildout(UserDict.DictMixin):
                 newest=self.newest,
                 allow_hosts=self._allow_hosts,
                 include_site_packages=_sys_executable_has_broken_dash_S,
-                prefer_final = self.prefer_final_build_system,
+                prefer_final=not self.accept_buildout_test_releases,
                 )
 
         # Now copy buildout and setuptools eggs, and record destination eggs:
@@ -373,7 +373,9 @@ class Buildout(UserDict.DictMixin):
                     else:
                         shutil.copy2(dist.location, dest)
 
-        # Create buildout script
+        # Create buildout script.
+        # Ideally the (possibly) new version of buildout would get a
+        # chance to write the script.  Not sure how to do that.
         ws = pkg_resources.WorkingSet(entries)
         ws.require('zc.buildout')
         partsdir = os.path.join(options['parts-directory'], 'buildout')
@@ -386,12 +388,19 @@ class Buildout(UserDict.DictMixin):
         else:
             assert relative_paths == 'false'
             relative_paths = ''
-        # Ideally the (possibly) new version of buildout would get a
-        # chance to write the script.  Not sure how to do that.
+        if (self.accept_buildout_test_releases and
+            self._annotated['buildout']['accept-buildout-test-releases'][1] ==
+            'COMMAND_LINE_VALUE'):
+            # Bootstrap was called with '--accept-buildout-test-releases'.
+            # Continue to honor that setting.
+            script_initialization = _early_release_initialization_code
+        else:
+            script_initialization = ''
         zc.buildout.easy_install.sitepackage_safe_scripts(
             options['bin-directory'], ws, options['executable'], partsdir,
             reqs=['zc.buildout'], relative_paths=relative_paths,
-            include_site_packages=_sys_executable_has_broken_dash_S)
+            include_site_packages=_sys_executable_has_broken_dash_S,
+            script_initialization=script_initialization,)
 
     init = bootstrap
 
@@ -838,7 +847,7 @@ class Buildout(UserDict.DictMixin):
             path = [options['develop-eggs-directory']],
             allow_hosts = self._allow_hosts,
             include_site_packages=_sys_executable_has_broken_dash_S,
-            prefer_final=self.prefer_final_build_system,
+            prefer_final=not self.accept_buildout_test_releases,
             )
 
         upgraded = []
@@ -886,18 +895,27 @@ class Buildout(UserDict.DictMixin):
 
         # the new dist is different, so we've upgraded.
         # Update the scripts and return True
+        # Ideally the new version of buildout would get a chance to write the
+        # script.  Not sure how to do that.
         partsdir = os.path.join(options['parts-directory'], 'buildout')
         if os.path.exists(partsdir):
             # This is primarily for unit tests, in which .py files change too
             # fast for Python to know to regenerate the .pyc/.pyo files.
             shutil.rmtree(partsdir)
         os.mkdir(partsdir)
-        # Ideally the new version of buildout would get a chance to write the
-        # script.  Not sure how to do that.
+        if (self.accept_buildout_test_releases and
+            self._annotated['buildout']['accept-buildout-test-releases'][1] ==
+            'COMMAND_LINE_VALUE'):
+            # Bootstrap was called with '--accept-buildout-test-releases'.
+            # Continue to honor that setting.
+            script_initialization = _early_release_initialization_code
+        else:
+            script_initialization = ''
         zc.buildout.easy_install.sitepackage_safe_scripts(
             options['bin-directory'], ws, sys.executable, partsdir,
             reqs=['zc.buildout'],
-            include_site_packages=_sys_executable_has_broken_dash_S)
+            include_site_packages=_sys_executable_has_broken_dash_S,
+            script_initialization=script_initialization)
 
         # Restart
         args = map(zc.buildout.easy_install._safe_arg, sys.argv)
@@ -939,7 +957,7 @@ class Buildout(UserDict.DictMixin):
                 index = self['buildout'].get('index'),
                 newest=self.newest, allow_hosts=self._allow_hosts,
                 include_site_packages=_sys_executable_has_broken_dash_S,
-                prefer_final=self.prefer_final_build_system)
+                prefer_final=not self.accept_buildout_test_releases)
 
             # Clear cache because extensions might now let us read pages we
             # couldn't read before.
@@ -1055,7 +1073,7 @@ def _install_and_load(spec, group, entry, buildout):
                 newest=buildout.newest,
                 allow_hosts=buildout._allow_hosts,
                 include_site_packages=_sys_executable_has_broken_dash_S,
-                prefer_final=buildout.prefer_final_build_system)
+                prefer_final=not buildout.accept_buildout_test_releases)
 
         __doing__ = 'Loading %s recipe entry %s:%s.', group, spec, entry
         return pkg_resources.load_entry_point(
@@ -1514,7 +1532,7 @@ def _error(*message):
     sys.exit(1)
 
 _internal_error_template = """
-An internal error occured due to a bug in either zc.buildout or in a
+An internal error occurred due to a bug in either zc.buildout or in a
 recipe being used:
 """
 
@@ -1526,6 +1544,13 @@ def _check_for_unused_options_in_section(buildout, section):
                               % (section, ' '.join(map(repr, unused)))
                               )
 
+_early_release_initialization_code = """\
+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.')
+"""
+
 _usage = """\
 Usage: buildout [options] [assignments] [command [command arguments]]
 

src/zc/buildout/buildout.txt

@@ -463,7 +463,7 @@ leave previously created paths in place:
     While:
       Installing data-dir.
     <BLANKLINE>
-    An internal error occured due to a bug in either zc.buildout or in a
+    An internal error occurred due to a bug in either zc.buildout or in a
     recipe being used:
     Traceback (most recent call last):
       ...
@@ -495,7 +495,7 @@ If we fix the typo:
     While:
       Installing data-dir.
     <BLANKLINE>
-    An internal error occured due to a bug in either zc.buildout or in a
+    An internal error occurred due to a bug in either zc.buildout or in a
     recipe being used:
     Traceback (most recent call last):
     ...
@@ -572,7 +572,7 @@ When we rerun the buildout:
     While:
       Installing data-dir.
     <BLANKLINE>
-    An internal error occured due to a bug in either zc.buildout or in a
+    An internal error occurred due to a bug in either zc.buildout or in a
     recipe being used:
     Traceback (most recent call last):
     ...
@@ -653,7 +653,7 @@ directories will be created:
     While:
       Installing data-dir.
     <BLANKLINE>
-    An internal error occured due to a bug in either zc.buildout or in a
+    An internal error occurred due to a bug in either zc.buildout or in a
     recipe being used:
     Traceback (most recent call last):
     ...
@@ -729,6 +729,8 @@ COMMAND_LINE_VALUE).
     ==================
     <BLANKLINE>
     [buildout]
+    accept-buildout-test-releases= false
+        DEFAULT_VALUE
     allow-hosts= *
         DEFAULT_VALUE
     allow-picked-versions= true
@@ -765,8 +767,6 @@ COMMAND_LINE_VALUE).
         DEFAULT_VALUE
     prefer-final= false
         DEFAULT_VALUE
-    prefer-final-build-system= true
-        DEFAULT_VALUE
     python= buildout
         DEFAULT_VALUE
     relative-paths= false
@@ -1014,7 +1014,7 @@ Extending sections (macros)
 ---------------------------
 
 A section (other than the buildout section) can extend one or more
-other sections using the ``<`` option.  Options from the referenced
+other sections using the ``<=`` option.  Options from the referenced
 sections are copied to the refering section *before* variable
 substitution.  This, together with the ability to refer to variables
 of the current section allows sections to be used as macros.
@@ -2229,6 +2229,7 @@ database is shown.
     <BLANKLINE>
     Configuration data:
     [buildout]
+    accept-buildout-test-releases = false
     allow-hosts = *
     allow-picked-versions = true
     bin-directory = /sample-buildout/bin
@@ -2246,7 +2247,6 @@ database is shown.
     parts =
     parts-directory = /sample-buildout/parts
     prefer-final = false
-    prefer-final-build-system = true
     python = buildout
     relative-paths = false
     socket-timeout =
@@ -2502,19 +2502,18 @@ new releases, final releases are preferred.  If there are final
 releases that satisfy distribution requirements, then those releases
 are used even if newer non-final releases are available.
 
-A separate option controls the behavior of the build system itself.
-When buildout looks for recipes, extensions, and for updates to itself,
-it does prefer final releases by default, as of the 1.5.0 release.  The
-``prefer-final-build-system`` option will let you override this behavior.
-
-  [buildout]
-  ...
-  prefer-final-build-system = false
-
 In buildout version 2, all final releases will be preferred by
 default--that is ``prefer-final`` will also default to 'true'. You will
 then need to use a 'false' value for ``prefer-final`` to get the newest
-releases, like with ``prefer-final-build-system``.
+releases.
+
+A separate option controls the behavior of the build system itself.
+When buildout looks for recipes, extensions, and for updates to itself,
+it does prefer final releases by default, as of the 1.5.0 release.  The
+``accept-buildout-test-releases`` option will let you override this behavior.
+However, it is typically changed by the --accept-buildout-test-releases
+option to the bootstrap script, since bootstrapping is the first step to
+selecting a buildout.
 
 Finding distributions
 ---------------------

src/zc/buildout/debugging.txt

@@ -5,12 +5,12 @@ Buildouts can be pretty complex.  When things go wrong, it isn't
 always obvious why.  Errors can occur due to problems in user input or
 due to bugs in zc.buildout or recipes.  When an error occurs, Python's
 post-mortem debugger can be used to inspect the state of the buildout
-or recipe code were there error occured.  To enable this, use the -D
+or recipe code where the error occurred.  To enable this, use the -D
 option to the buildout.  Let's create a recipe that has a bug:
 
     >>> mkdir(sample_buildout, 'recipes')
 
-    >>> write(sample_buildout, 'recipes', 'mkdir.py', 
+    >>> write(sample_buildout, 'recipes', 'mkdir.py',
     ... """
     ... import os, zc.buildout
     ...
@@ -35,7 +35,7 @@ option to the buildout.  Let's create a recipe that has a bug:
     >>> write(sample_buildout, 'recipes', 'setup.py',
     ... """
     ... from setuptools import setup
-    ... 
+    ...
     ... setup(name = "recipes",
     ...       entry_points = {'zc.buildout': ['mkdir = mkdir:Mkdir']},
     ...       )

src/zc/buildout/easy_install.py

@@ -577,7 +577,7 @@ class Installer:
 
             if exit_code:
                 logger.error(
-                    "An error occured when trying to install %s. "
+                    "An error occurred when trying to install %s. "
                     "Look above this message for any errors that "
                     "were output by easy_install.",
                     dist)

src/zc/buildout/extends-cache.txt

@@ -383,7 +383,7 @@ Error: Couldn't download 'http://localhost/base.cfg' in offline mode.
 While:
   Installing.
   Checking for upgrades.
-An internal error occured ...
+An internal error occurred ...
 ValueError: install_from_cache set to true with no download cache
 
 

src/zc/buildout/tests.py

@@ -1442,7 +1442,7 @@ def internal_errors():
       Getting section data-dir.
       Initializing part data-dir.
     <BLANKLINE>
-    An internal error occured due to a bug in either zc.buildout or in a
+    An internal error occurred due to a bug in either zc.buildout or in a
     recipe being used:
     Traceback (most recent call last):
     ...
@@ -2615,7 +2615,7 @@ if sys.version_info > (2, 4):
           Initializing section x.
           Loading zc.buildout recipe entry zc.buildout.testexit:default.
         <BLANKLINE>
-        An internal error occured due to a bug in either zc.buildout or in a
+        An internal error occurred due to a bug in either zc.buildout or in a
         recipe being used:
         Traceback (most recent call last):
         ...
@@ -3128,9 +3128,11 @@ We get an error if we specify anything but true or false:
 
 def buildout_prefer_final_build_system_option():
     """
-The prefer-final-build-system buildout option can be used for overriding
+The accept-buildout-test-releases buildout option can be used for overriding
 the default preference for final distributions for recipes, buildout
-extensions, and buildout itself.
+extensions, and buildout itself.  It is usually controlled via the bootstrap
+script rather than in the configuration file, but we will test the machinery
+using the file.
 
 Set up.  This creates sdists for demorecipe 1.0 and 1.1b1, and for
 demoextension 1.0 and 1.1b1.
@@ -3138,7 +3140,7 @@ demoextension 1.0 and 1.1b1.
     >>> create_sample_recipe_sdists(sample_eggs)
     >>> create_sample_extension_sdists(sample_eggs)
 
-The default is prefer-final-build-system = true:
+The default is accept-buildout-test-releases = false:
 
     >>> write('buildout.cfg',
     ... '''
@@ -3161,7 +3163,7 @@ The default is prefer-final-build-system = true:
 Here we see that the final versions of demorecipe and demoextension were used.
 
 We get the same behavior if we explicitly state that
-prefer-final-build-system = true.
+accept-buildout-test-releases = false.
 
     >>> write('buildout.cfg',
     ... '''
@@ -3169,7 +3171,7 @@ prefer-final-build-system = true.
     ... parts = demo
     ... find-links = %(link_server)s
     ... extensions = demoextension
-    ... prefer-final-build-system = true
+    ... accept-buildout-test-releases = false
     ...
     ... [demo]
     ... recipe = demorecipe
@@ -3182,7 +3184,7 @@ prefer-final-build-system = true.
     Picked: demorecipe = 1.0
     ...
 
-If we specify prefer-final-build-system = false, we'll get the newest
+If we specify accept-buildout-test-releases = true, we'll get the newest
 distributions in the build system:
 
     >>> write('buildout.cfg',
@@ -3191,7 +3193,7 @@ distributions in the build system:
     ... parts = demo
     ... find-links = %(link_server)s
     ... extensions = demoextension
-    ... prefer-final-build-system = false
+    ... accept-buildout-test-releases = true
     ...
     ... [demo]
     ... recipe = demorecipe
@@ -3212,7 +3214,7 @@ We get an error if we specify anything but true or false:
     ... parts = demo
     ... find-links = %(link_server)s
     ... extensions = demoextension
-    ... prefer-final-build-system = no
+    ... accept-buildout-test-releases = no
     ...
     ... [demo]
     ... recipe = demorecipe
@@ -3221,7 +3223,7 @@ We get an error if we specify anything but true or false:
     >>> print system(buildout+' -v'), # doctest: +ELLIPSIS
     While:
       Initializing.
-    Error: Invalid value for prefer-final-build-system option: no
+    Error: Invalid value for accept-buildout-test-releases option: no
 
     """
 

src/zc/buildout/update.txt

@@ -81,8 +81,10 @@ new versions found in new releases:
 
 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,
-or use the ``prefer-final-build-system = false`` discussed below.
+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:
 
@@ -194,9 +196,14 @@ directory:
 
     >>> ls('bin')
 
-Notice that, as mentioned above, the ``prefer-final-build-system =
-false`` means that newer non-final versions of these dependencies are
-preferred.
+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',
@@ -206,20 +213,39 @@ preferred.
     ... index = %(new_releases)s
     ... parts = show-versions
     ... develop = showversions
-    ... prefer-final-build-system = false
     ...
     ... [show-versions]
     ... recipe = showversions
     ... """ % dict(new_releases=new_releases))
 
-    >>> print system(buildout),
+    >>> 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.')
+    ...