# HG changeset patch
# User Pierre-Yves David <pierre-yves.david@octobus.net>
# Date 1709522013 -3600
# Node ID 5d0d510d2db12b4e004dff73a4140965e2f3aaab
# Parent  6a98abbb95ee0504ff50d42f94b8aa9a2b9abfa5
config: document the storage and format sections

This should help people to put configuration in the right section.

diff -r 6a98abbb95ee -r 5d0d510d2db1 mercurial/configitems.toml
--- a/mercurial/configitems.toml	Fri Feb 23 15:55:53 2024 +0100
+++ b/mercurial/configitems.toml	Mon Mar 04 04:13:33 2024 +0100
@@ -1160,6 +1160,19 @@
 default = false
 generic = true
 
+
+# The format section is dedicated to control of the repository on disk format
+# and constraints.
+#
+# A format change affects which data is expected to be stored in the repository
+# and how. It impacts other client whichever their version are, format change
+# often comes with an associated entry in the requirements.
+#
+# The option are usually in the form `use-xxx-yyy` (with xxx-yy the feature name).
+#
+# To configure details of how the repository is accessed, without affect the
+# repository formats, see the `storage section`.
+
 [[items]]
 section = "format"
 name = "bookmarks-in-store"
@@ -2102,6 +2115,15 @@
 default = true
 experimental = true
 
+
+# The "storage" section house config options that change how the repository
+# data are accessed by  the current process but does not affects the on disk
+# format. They can also adjust how the storage is computed, but without affect
+# compatibility wither other clients.
+#
+# For deeper format change, see the `format` section.
+
+
 [[items]]
 section = "storage"
 name = "dirstate-v2.slow-path"