[pve-devel] [PATCH v4 docs 1/9] configuration files: add general section

[Fiona Ebner]

Explain the mixed casing styles for (sub-)properties in configuration
files and plans regarding the future.

Signed-off-by: Fiona Ebner <f.ebner at proxmox.com>
---

New in v4.

 configuration-files.adoc | 28 ++++++++++++++++++++++++++++
 pve-admin-guide.adoc     |  2 +-
 2 files changed, 29 insertions(+), 1 deletion(-)
 create mode 100644 configuration-files.adoc

diff --git a/configuration-files.adoc b/configuration-files.adoc
new file mode 100644
index 0000000..aeb6cf4
--- /dev/null
+++ b/configuration-files.adoc
@@ -0,0 +1,28 @@
+[[configuration_files]]
+General
+=======
+
+Most configuration files in {pve} reside on the
+xref:chapter_pmxcfs[shared cluster file system] mounted at `/etc/pve`. There are
+exceptions, like the node-specific configuration file for backups in
+`/etc/vzdump.conf`.
+
+Usually, the properties in a configuration file are derived from the JSON Schema
+that is also used for the associated API endpoints.
+
+[[configuration_files_casing]]
+Casing of Property Names
+------------------------
+
+Historically, longer properties (and sub-properties) often used `snake_case`, or
+were written as one word. This can likely be attributed to the {pve} stack being
+developed mostly in the programming language Perl, where access to properties
+using `kebab-case` requires additional quotes, as well as less style enforcement
+during early development, so different developers used different conventions.
+
+For new properties, `kebab-case` is the preferred way and it is planned to
+introduce aliases for existing `snake_case` properties, and in the long term,
+switch over to `kebab-case` for the API, CLI and in-use configuration files
+while maintaining backwards-compatibility when restoring a configuration.
+
+include::datacenter.cfg.adoc[]
diff --git a/pve-admin-guide.adoc b/pve-admin-guide.adoc
index 2a37df4..9a0ec85 100644
--- a/pve-admin-guide.adoc
+++ b/pve-admin-guide.adoc
@@ -308,7 +308,7 @@ Configuration Files
 -------------------
 
 :leveloffset: 2
-include::datacenter.cfg.adoc[]
+include::configuration-files.adoc[]
 
 :leveloffset: 0
 
-- 
2.39.5