configuration files: add general section

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

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

diff --git a/configuration-files.adoc b/configuration-files.adoc
new file mode 100644 (file)
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 2a37df40a5289c629d86262b53c81a450e21cb82..9a0ec856a1946e1a33f9df19ad167155792d71cb 100644 (file)
--- 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