Add more wording on upgrade/downgrade of databases.

Add "config_base" configuration string to wiredtiger_open, controls the
creation of the base-configuration file.

Add a test, merge test_isnew.py and test_gethome.py plus the new test
into test_home.py.:

1 files changed, 22 insertions, 7 deletions

diff --git a/src/docs/database-config.dox b/src/docs/database-config.dox
index b86971ca450..b8dee0be980 100644
--- a/src/docs/database-config.dox
+++ b/src/docs/database-config.dox
@@ -67,12 +67,27 @@ replaced with commas.
 
 @section config_base WiredTiger.basecfg file
 
-When a WiredTiger database is created, the configuration string passed
-to ::wiredtiger_open is saved to a WiredTiger home directory file named
-\c WiredTiger.basecfg, and that configuration file is read whenever the
-database is subsequently opened.
-
-Users should not edit this file, set the \c WIREDTIGER_CONFIG
-environment variable or create a \c WiredTiger.config file instead.
+When a WiredTiger database is created, non-default configuration
+information specified to ::wiredtiger_open is saved to a WiredTiger home
+directory file named \c WiredTiger.basecfg, and that configuration file
+is read whenever the database is subsequently opened.
+
+For example, if a shared library extensions are required, those settings
+will be saved to the base configuration file so it's easier to write
+general-purpose applications that might not be aware of how a particular
+database was created and configured.
+
+Users should not not edit this file, set the \c WIREDTIGER_CONFIG
+environment variable or create a \c WiredTiger.config file instead, as
+those settings override the settings in the base configuration file.
+
+This file is a potential problem for applications that want to retain
+the ability to downgrade to previous releases. If a new database is
+created after an upgrade, the base configuration file might have
+configuration strings that would cause a previous version of the
+application to fail. For this reason, applications that may want to
+downgrade should configure the ::wiredtiger_open value \c config_base
+to \c false so the base configuration file is not written as part of
+database create.
 
 */