Launchpad #344098:

- In ``skel/etc/zope.conf.ing``, replaced commented-out
  ``read-only-database`` option, which is deprecated, with pointers to the
   appropos sections of ZODB's ``component.xml``.

- Updated the description of the ``zserver-read-only-mode`` directive to
  indicate its correct semantics (suppressing log / pid / lock files).
  
- Added deprecation to the ``read-only-database`` option, which has had no
  effect since Zope 2.6.

doc/CHANGES.rst

@@ -35,6 +35,13 @@ Restructuring
 Bugs Fixed
 ++++++++++
 
+- Launchpad#344098: in ``skel/etc/zope.conf.ing``, replaced commented-out
+  ``read-only-database`` option, which is deprecated, with pointers to the
+  appropos sections of ZODB's ``component.xml``.  Updated the description
+  of the ``zserver-read-only-mode`` directive to indicate its correct
+  semantics (suppressing log / pid / lock files).  Added deprecation to the
+  ``read-only-database`` option, which has had no effect since Zope 2.6.
+
 - "Permission tab": correct wrong form parameter for
   the user-permission report
 

src/Zope2/Startup/handlers.py

@@ -59,10 +59,6 @@ def datetime_format(value):
     value and _setenv('DATETIME_FORMAT', value)
     return value
 
-def zserver_read_only_mode(value):
-    value and _setenv('ZOPE_READ_ONLY', '1')
-    return value
-
 def automatically_quote_dtml_request_data(value):
     not value and _setenv('ZOPE_DTML_REQUEST_AUTOQUOTE', '0')
     return value
@@ -98,7 +94,14 @@ def database_quota_size(value):
     return value
 
 def read_only_database(value):
-    value and _setenv('ZOPE_READ_ONLY', '1')
+    # This handler exists only for BBB:  using the 'read-only-database'
+    # directive in a config file is deprecated.
+    if value is not None:
+        import warnings
+        warnings.warn("The 'read-only-database' configuration option is "
+                    "deprecated; please use the correct optoin inside the "
+                    "section defining the appropriate storage.",
+                    DeprecationWarning, stacklevel=2)
     return value
 
 def zeo_client_name(value):

src/Zope2/Startup/zopeschema.xml

@@ -462,14 +462,13 @@
     </description>
   </key>
 
-  <key name="zserver-read-only-mode" datatype="boolean" default="off"
-       handler="zserver_read_only_mode">
+  <key name="zserver-read-only-mode" datatype="boolean" default="off">
     <description>
-      If this variable is set, then the database is opened in read
-      only mode.  If this variable is set to a string parsable by
-      DateTime.DateTime, then the database is opened read-only as of
-      the time given.  Note that changes made by another process after
-      the database has been opened are not visible.
+      If this variable is set, then the server will not create or write
+      to any log, pid, or lock files when running.  Note that this option
+      does *not* govern opening storages in read-only mode:  for that
+      use, please use the appropriate flag in the section which configures
+      each storage.
     </description>
   </key>
 
@@ -794,9 +793,9 @@
   <key name="read-only-database" datatype="boolean"
        handler="read_only_database">
      <description>
-     If this directive is set to "on", the main Zope
-     FileStorage-backed ZODB database will be opened in read-only
-     mode.
+      Deprecated option, no longer has any effect.  To configure opening
+      storages in read-only mode:  please use the appropriate flag in the
+      section which configures each storage.
      </description>
      <metadefault>off</metadefault>
   </key>

src/Zope2/utilities/skel/etc/zope.conf.in

@@ -736,19 +736,6 @@ instancehome $INSTANCE
 #    database-quota-size 1000000
 
 
-# Directive: read-only-database
-#
-# Description:
-#     This causes the main Zope FileStorage-backed ZODB to be opened in
-#     read-only mode.
-#
-# Default: off
-#
-# Example:
-#
-#    read-only-database on
-
-
 # Directive: zeo-client-name
 #
 # Description:
@@ -1040,6 +1027,8 @@ instancehome $INSTANCE
 <zodb_db main>
     # Main FileStorage database
     <filestorage>
+      # See .../ZODB/component.xml for directives (sectiontype
+      # "filestorage").
       path $INSTANCE/var/Data.fs
     </filestorage>
     mount-point /
@@ -1070,6 +1059,8 @@ instancehome $INSTANCE
 #   # ZODB cache, in number of objects
 #   cache-size 5000
 #   <zeoclient>
+#     # See .../ZODB/component.xml for directives (sectiontype
+#     # "zeoclient").
 #     server localhost:8100
 #     storage 1
 #     name zeostorage