Explain the mixed casing styles for (sub-)properties in configuration
files and plans regarding the future.
Signed-off-by: Fiona Ebner <f.eb...@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
_______________________________________________
pve-devel mailing list
pve-devel@lists.proxmox.com
https://lists.proxmox.com/cgi-bin/mailman/listinfo/pve-devel
