all lists on lists.proxmox.com
 help / color / mirror / Atom feed
From: Fiona Ebner <f.ebner@proxmox.com>
To: pve-devel@lists.proxmox.com
Subject: [pve-devel] [PATCH v4 docs 1/9] configuration files: add general section
Date: Mon, 11 Nov 2024 14:54:28 +0100	[thread overview]
Message-ID: <20241111135436.82773-2-f.ebner@proxmox.com> (raw)
In-Reply-To: <20241111135436.82773-1-f.ebner@proxmox.com>

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>
---

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


  reply	other threads:[~2024-11-11 13:56 UTC|newest]

Thread overview: 15+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2024-11-11 13:54 [pve-devel] [PATCH-SERIES v4 docs/qemu-server] more robust handling of fleecing images Fiona Ebner
2024-11-11 13:54 ` Fiona Ebner [this message]
2024-11-11 13:54 ` [pve-devel] [PATCH v4 docs 2/9] cli appendix: reference section about casing style Fiona Ebner
2024-11-11 13:54 ` [pve-devel] [PATCH v4 qemu-server 3/9] backup: prepare: factor out getting running status Fiona Ebner
2024-11-11 13:54 ` [pve-devel] [PATCH v4 qemu-server 4/9] backup: prepare: cancel previous job if still running Fiona Ebner
2024-11-11 13:54 ` [pve-devel] [PATCH v4 qemu-server 5/9] parse config: allow config keys with minus sign Fiona Ebner
2024-11-11 13:54 ` [pve-devel] [PATCH v4 qemu-server 6/9] schema: add fleecing-images config property Fiona Ebner
2024-11-11 13:54 ` [pve-devel] [PATCH v4 qemu-server 7/9] fix #5440: vzdump: better cleanup fleecing images after hard errors Fiona Ebner
2024-11-11 13:54 ` [pve-devel] [PATCH v4 qemu-server 8/9] migration: attempt to clean up potential left-over fleecing images Fiona Ebner
2024-11-11 13:54 ` [pve-devel] [PATCH v4 qemu-server 9/9] destroy vm: " Fiona Ebner
2024-11-17 18:43 ` [pve-devel] partially-applied: [PATCH-SERIES v4 docs/qemu-server] more robust handling of " Thomas Lamprecht
2024-11-18  8:52   ` Fiona Ebner
2024-11-18 11:03     ` Thomas Lamprecht
2024-11-18 20:31     ` Thomas Lamprecht
2024-11-19  9:00       ` Fiona Ebner

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=20241111135436.82773-2-f.ebner@proxmox.com \
    --to=f.ebner@proxmox.com \
    --cc=pve-devel@lists.proxmox.com \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body.
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.
Service provided by Proxmox Server Solutions GmbH | Privacy | Legal