Mention "bug fix feature flags" separatelydelay_appending_ruby_scope

These settings are not regular configurations, so I think we should
mention them separately.

4 files changed, 72 insertions, 50 deletions

diff --git a/man/bundle-config.1 b/man/bundle-config.1
index 09e8b0628b..7171bc9797 100644
--- a/man/bundle-config.1
+++ b/man/bundle-config.1
@@ -211,9 +211,6 @@ The following is a list of all configuration keys and their purpose\. You can le
 \fBglobal_gem_cache\fR (\fBBUNDLE_GLOBAL_GEM_CACHE\fR): Whether Bundler should cache all gems globally, rather than locally to the installing Ruby installation\.
 .
 .IP "\(bu" 4
-\fBglobal_path_appends_ruby_scope\fR (\fBBUNDLE_GLOBAL_PATH_APPENDS_RUBY_SCOPE\fR): Whether Bundler should append the Ruby scope (e\.g\. engine and ABI version) to a globally\-configured path\.
-.
-.IP "\(bu" 4
 \fBignore_messages\fR (\fBBUNDLE_IGNORE_MESSAGES\fR): When set, no post install messages will be printed\. To silence a single gem, use dot notation like \fBignore_messages\.httparty true\fR\.
 .
 .IP "\(bu" 4
@@ -314,6 +311,13 @@ In general, you should set these settings per\-application by using the applicab
 .P
 You can set them globally either via environment variables or \fBbundle config\fR, whichever is preferable for your setup\. If you use both, environment variables will take preference over global settings\.
 .
+.SH "LIST OF EARLY OPT\-IN CONFIGURATION KEYS"
+The following is a list of configuration keys meant to only be used to early opt into bug fixes that are deemed to be too disruptive to be shipped on a non\-major release of Bundler\. The functionality they enable will be the default and only behavior in future versions of bundler\. Only set these settings to true\.
+.
+.TP
+\fBglobal_path_appends_ruby_scope\fR (\fBBUNDLE_GLOBAL_PATH_APPENDS_RUBY_SCOPE\fR)
+Whether Bundler should append the Ruby scope (e\.g\. engine and ABI version) to a globally\-configured path\.
+.
 .SH "LOCAL GIT REPOS"
 Bundler also allows you to work against a git repository locally instead of using the remote version\. This can be achieved by setting up a local override:
 .
diff --git a/man/bundle-config.1.txt b/man/bundle-config.1.txt
index d88e90c607..48bdd98a22 100644
--- a/man/bundle-config.1.txt
+++ b/man/bundle-config.1.txt
@@ -247,89 +247,84 @@ LIST OF AVAILABLE KEYS
 	   cache all gems globally, rather than locally to the installing Ruby
 	   installation.
 
-       o   global_path_appends_ruby_scope				 (BUN-
-	   DLE_GLOBAL_PATH_APPENDS_RUBY_SCOPE): Whether Bundler should	append
-	   the	Ruby scope (e.g. engine and ABI version) to a globally-config-
-	   ured path.
-
        o   ignore_messages (BUNDLE_IGNORE_MESSAGES): When set, no post install
 	   messages will be printed. To silence a single gem, use dot notation
 	   like ignore_messages.httparty true.
 
-       o   init_gems_rb (BUNDLE_INIT_GEMS_RB) Generate a gems.rb instead of  a
+       o   init_gems_rb  (BUNDLE_INIT_GEMS_RB) Generate a gems.rb instead of a
 	   Gemfile when running bundle init.
 
-       o   jobs  (BUNDLE_JOBS): The number of gems Bundler can install in par-
+       o   jobs (BUNDLE_JOBS): The number of gems Bundler can install in  par-
 	   allel. Defaults to 1.
 
-       o   no_install (BUNDLE_NO_INSTALL): Whether bundle package should  skip
+       o   no_install  (BUNDLE_NO_INSTALL): Whether bundle package should skip
 	   installing gems.
 
-       o   no_prune  (BUNDLE_NO_PRUNE):  Whether Bundler should leave outdated
+       o   no_prune (BUNDLE_NO_PRUNE): Whether Bundler should  leave  outdated
 	   gems unpruned when caching.
 
        o   only_update_to_newer_versions     (BUNDLE_ONLY_UPDATE_TO_NEWER_VER-
 	   SIONS): During bundle update, only resolve to newer versions of the
 	   gems in the lockfile.
 
-       o   path (BUNDLE_PATH): The location on disk where  all	gems  in  your
+       o   path  (BUNDLE_PATH):  The  location	on disk where all gems in your
 	   bundle will be located regardless of $GEM_HOME or $GEM_PATH values.
-	   Bundle gems not found in this location will be installed by	bundle
-	   install.  Defaults  to Gem.dir. When --deployment is used, defaults
+	   Bundle  gems not found in this location will be installed by bundle
+	   install. Defaults to Gem.dir. When --deployment is  used,  defaults
 	   to vendor/bundle.
 
-       o   path.system (BUNDLE_PATH__SYSTEM):  Whether	Bundler  will  install
+       o   path.system	(BUNDLE_PATH__SYSTEM):	Whether  Bundler  will install
 	   gems into the default system path (Gem.dir).
 
-       o   path_relative_to_cwd   (BUNDLE_PATH_RELATIVE_TO_CWD)  Makes	--path
+       o   path_relative_to_cwd  (BUNDLE_PATH_RELATIVE_TO_CWD)	Makes	--path
 	   relative to the CWD instead of the Gemfile.
 
        o   plugins (BUNDLE_PLUGINS): Enable Bundler's experimental plugin sys-
 	   tem.
 
-       o   prefer_patch  (BUNDLE_PREFER_PATCH):  Prefer  updating only to next
-	   patch version during updates. Makes bundle update calls  equivalent
+       o   prefer_patch (BUNDLE_PREFER_PATCH): Prefer updating	only  to  next
+	   patch  version during updates. Makes bundle update calls equivalent
 	   to bundler update --patch.
 
-       o   print_only_version_number  (BUNDLE_PRINT_ONLY_VERSION_NUMBER) Print
+       o   print_only_version_number (BUNDLE_PRINT_ONLY_VERSION_NUMBER)  Print
 	   only version number from bundler --version.
 
-       o   redirect (BUNDLE_REDIRECT): The number  of  redirects  allowed  for
+       o   redirect  (BUNDLE_REDIRECT):  The  number  of redirects allowed for
 	   network requests. Defaults to 5.
 
-       o   retry  (BUNDLE_RETRY):  The number of times to retry failed network
+       o   retry (BUNDLE_RETRY): The number of times to retry  failed  network
 	   requests. Defaults to 3.
 
        o   setup_makes_kernel_gem_public   (BUNDLE_SETUP_MAKES_KERNEL_GEM_PUB-
-	   LIC):  Have	Bundler.setup  make the Kernel#gem method public, even
+	   LIC): Have Bundler.setup make the Kernel#gem  method  public,  even
 	   though RubyGems declares it as private.
 
-       o   shebang (BUNDLE_SHEBANG): The program name that should  be  invoked
-	   for	generated  binstubs. Defaults to the ruby install name used to
+       o   shebang  (BUNDLE_SHEBANG):  The program name that should be invoked
+	   for generated binstubs. Defaults to the ruby install name  used  to
 	   generate the binstub.
 
        o   silence_deprecations (BUNDLE_SILENCE_DEPRECATIONS): Whether Bundler
-	   should  silence  deprecation  warnings  for	behavior  that will be
+	   should silence deprecation  warnings  for  behavior	that  will  be
 	   changed in the next major version.
 
-       o   silence_root_warning  (BUNDLE_SILENCE_ROOT_WARNING):  Silence   the
+       o   silence_root_warning   (BUNDLE_SILENCE_ROOT_WARNING):  Silence  the
 	   warning Bundler prints when installing gems as root.
 
        o   skip_default_git_sources (BUNDLE_SKIP_DEFAULT_GIT_SOURCES): Whether
 	   Bundler should skip adding default git source shortcuts to the Gem-
 	   file DSL.
 
-       o   specific_platform   (BUNDLE_SPECIFIC_PLATFORM):  Allow  bundler  to
+       o   specific_platform  (BUNDLE_SPECIFIC_PLATFORM):  Allow  bundler   to
 	   resolve for the specific running platform and store it in the lock-
 	   file, instead of only using a generic platform. A specific platform
-	   is the exact platform triple reported by Gem::Platform.local,  such
-	   as  x86_64-darwin-16  or  universal-java-1.8.  On  the  other hand,
-	   generic platforms are those such as ruby, mswin, or java.  In  this
-	   example,  x86_64-darwin-16 would map to ruby and universal-java-1.8
+	   is  the exact platform triple reported by Gem::Platform.local, such
+	   as x86_64-darwin-16	or  universal-java-1.8.  On  the  other  hand,
+	   generic  platforms  are those such as ruby, mswin, or java. In this
+	   example, x86_64-darwin-16 would map to ruby and  universal-java-1.8
 	   to java.
 
-       o   ssl_ca_cert (BUNDLE_SSL_CA_CERT): Path to a designated CA  certifi-
-	   cate  file  or  folder containing multiple certificates for trusted
+       o   ssl_ca_cert	(BUNDLE_SSL_CA_CERT): Path to a designated CA certifi-
+	   cate file or folder containing multiple  certificates  for  trusted
 	   CAs in PEM format.
 
        o   ssl_client_cert (BUNDLE_SSL_CLIENT_CERT): Path to a designated file
@@ -339,42 +334,53 @@ LIST OF AVAILABLE KEYS
 	   Bundler uses when making HTTPS requests. Defaults to verify peer.
 
        o   suppress_install_using_messages (BUNDLE_SUPPRESS_INSTALL_USING_MES-
-	   SAGES):  Avoid printing Using ... messages during installation when
+	   SAGES): Avoid printing Using ... messages during installation  when
 	   the version of a gem has not changed.
 
-       o   system_bindir (BUNDLE_SYSTEM_BINDIR): The location  where  RubyGems
+       o   system_bindir  (BUNDLE_SYSTEM_BINDIR):  The location where RubyGems
 	   installs binstubs. Defaults to Gem.bindir.
 
        o   timeout (BUNDLE_TIMEOUT): The seconds allowed before timing out for
 	   network requests. Defaults to 10.
 
        o   unlock_source_unlocks_spec	  (BUNDLE_UNLOCK_SOURCE_UNLOCKS_SPEC):
-	   Whether  running bundle update --source NAME unlocks a gem with the
+	   Whether running bundle update --source NAME unlocks a gem with  the
 	   given name. Defaults to true.
 
-       o   update_requires_all_flag (BUNDLE_UPDATE_REQUIRES_ALL_FLAG)  Require
-	   passing  --all  to bundle update when everything should be updated,
+       o   update_requires_all_flag  (BUNDLE_UPDATE_REQUIRES_ALL_FLAG) Require
+	   passing --all to bundle update when everything should  be  updated,
 	   and disallow passing no options to bundle update.
 
-       o   user_agent (BUNDLE_USER_AGENT):  The  custom  user  agent  fragment
+       o   user_agent  (BUNDLE_USER_AGENT):  The  custom  user	agent fragment
 	   Bundler includes in API requests.
 
        o   with (BUNDLE_WITH): A :-separated list of groups whose gems bundler
 	   should install.
 
-       o   without (BUNDLE_WITHOUT): A :-separated list of groups  whose  gems
+       o   without  (BUNDLE_WITHOUT):  A :-separated list of groups whose gems
 	   bundler should not install.
 
 
 
-       In  general, you should set these settings per-application by using the
-       applicable flag to the bundle install(1) bundle-install.1.html or  bun-
+       In general, you should set these settings per-application by using  the
+       applicable  flag to the bundle install(1) bundle-install.1.html or bun-
        dle package(1) bundle-package.1.html command.
 
-       You  can  set  them globally either via environment variables or bundle
-       config, whichever is preferable for your setup. If you use both,  envi-
+       You can set them globally either via environment  variables  or	bundle
+       config,	whichever is preferable for your setup. If you use both, envi-
        ronment variables will take preference over global settings.
 
+LIST OF EARLY OPT-IN CONFIGURATION KEYS
+       The following is a list of configuration keys meant to only be used  to
+       early  opt  into  bug  fixes that are deemed to be too disruptive to be
+       shipped on a non-major  release	of  Bundler.  The  functionality  they
+       enable  will  be  the  default  and only behavior in future versions of
+       bundler. Only set these settings to true.
+
+       global_path_appends_ruby_scope (BUNDLE_GLOBAL_PATH_APPENDS_RUBY_SCOPE)
+	      Whether Bundler should append the Ruby scope  (e.g.  engine  and
+	      ABI version) to a globally-configured path.
+
 LOCAL GIT REPOS
        Bundler	also  allows  you  to  work  against  a git repository locally
        instead of using the remote version. This can be achieved by setting up
diff --git a/man/bundle-config.ronn b/man/bundle-config.ronn
index dafd9ed06b..b73dcfd3ad 100644
--- a/man/bundle-config.ronn
+++ b/man/bundle-config.ronn
@@ -205,9 +205,6 @@ learn more about their operation in [bundle install(1)](bundle-install.1.html).
 * `global_gem_cache` (`BUNDLE_GLOBAL_GEM_CACHE`):
    Whether Bundler should cache all gems globally, rather than locally to the
    installing Ruby installation.
-* `global_path_appends_ruby_scope` (`BUNDLE_GLOBAL_PATH_APPENDS_RUBY_SCOPE`):
-   Whether Bundler should append the Ruby scope (e.g. engine and ABI version)
-   to a globally-configured path.
 * `ignore_messages` (`BUNDLE_IGNORE_MESSAGES`): When set, no post install
    messages will be printed. To silence a single gem, use dot notation like
    `ignore_messages.httparty true`.
@@ -299,6 +296,17 @@ You can set them globally either via environment variables or `bundle config`,
 whichever is preferable for your setup. If you use both, environment variables
 will take preference over global settings.
 
+## LIST OF EARLY OPT-IN CONFIGURATION KEYS
+
+The following is a list of configuration keys meant to only be used to early opt
+into bug fixes that are deemed to be too disruptive to be shipped on a non-major
+release of Bundler. The functionality they enable will be the default and only
+behavior in future versions of bundler. Only set these settings to true.
+
+* `global_path_appends_ruby_scope` (`BUNDLE_GLOBAL_PATH_APPENDS_RUBY_SCOPE`):
+   Whether Bundler should append the Ruby scope (e.g. engine and ABI version)
+   to a globally-configured path.
+
 ## LOCAL GIT REPOS
 
 Bundler also allows you to work against a git repository locally
diff --git a/spec/quality_spec.rb b/spec/quality_spec.rb
index 09e59d88ae..509e55cb44 100644
--- a/spec/quality_spec.rb
+++ b/spec/quality_spec.rb
@@ -192,6 +192,7 @@ RSpec.describe "The library itself" do
 
     all_settings = Hash.new {|h, k| h[k] = [] }
     documented_settings = []
+    documented_setting_sections = []
 
     Bundler::Settings::BOOL_KEYS.each {|k| all_settings[k] << "in Bundler::Settings::BOOL_KEYS" }
     Bundler::Settings::NUMBER_KEYS.each {|k| all_settings[k] << "in Bundler::Settings::NUMBER_KEYS" }
@@ -204,7 +205,8 @@ RSpec.describe "The library itself" do
           line.scan(/Bundler\.settings\[:#{key_pattern}\]/).flatten.each {|s| all_settings[s] << "referenced at `#{filename}:#{number.succ}`" }
         end
       end
-      documented_settings = File.read("man/bundle-config.ronn")[/LIST OF AVAILABLE KEYS.*/m].scan(/^\* `#{key_pattern}`/).flatten
+      documented_setting_sections = File.read("man/bundle-config.ronn").split(/LIST OF .* KEYS/)[1..-1].map {|section| section.scan(/^\* `#{key_pattern}`/).flatten }
+      documented_settings = documented_setting_sections.flatten
     end
 
     documented_settings.each do |s|
@@ -221,7 +223,9 @@ RSpec.describe "The library itself" do
 
     expect(error_messages.sort).to be_well_formed
 
-    expect(documented_settings).to be_sorted
+    documented_setting_sections.each do |documented_setting_section|
+      expect(documented_setting_section).to be_sorted
+    end
   end
 
   it "can still be built" do