From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from firstgate.proxmox.com (firstgate.proxmox.com [IPv6:2a01:7e0:0:424::9]) by lore.proxmox.com (Postfix) with ESMTPS id B77271FF187 for ; Fri, 19 Dec 2025 20:46:10 +0100 (CET) Received: from firstgate.proxmox.com (localhost [127.0.0.1]) by firstgate.proxmox.com (Proxmox) with ESMTP id 183C11499C; Fri, 19 Dec 2025 20:45:54 +0100 (CET) From: "Max R. Carrara" To: pve-devel@lists.proxmox.com Date: Fri, 19 Dec 2025 20:44:54 +0100 Message-ID: <20251219194511.840583-20-m.carrara@proxmox.com> X-Mailer: git-send-email 2.47.3 In-Reply-To: <20251219194511.840583-1-m.carrara@proxmox.com> References: <20251219194511.840583-1-m.carrara@proxmox.com> MIME-Version: 1.0 X-Bm-Milter-Handled: 55990f41-d878-4baa-be0a-ee34c49e34d2 X-Bm-Transport-Timestamp: 1766173538096 X-SPAM-LEVEL: Spam detection results: 0 AWL 0.083 Adjusted score from AWL reputation of From: address BAYES_00 -1.9 Bayes spam probability is 0 to 1% DMARC_MISSING 0.1 Missing DMARC policy KAM_DMARC_STATUS 0.01 Test Rule for DKIM or SPF Failure with Strict Alignment SPF_HELO_NONE 0.001 SPF: HELO does not publish an SPF Record SPF_PASS -0.001 SPF: sender matches SPF record Subject: [pve-devel] [PATCH pve-common v1 19/23] sectionconfig: extend / correct docstring of `private()` method X-BeenThere: pve-devel@lists.proxmox.com X-Mailman-Version: 2.1.29 Precedence: list List-Id: Proxmox VE development discussion List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Reply-To: Proxmox VE development discussion Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: 7bit Errors-To: pve-devel-bounces@lists.proxmox.com Sender: "pve-devel" At the end of the docstring, note that .. * one really should only declare default properties as required in very special cases, such as using a property as an identifier * and that only attributes specific to PVE::JSONSchema should be declared on default properties The latter case in particular was mentioned off-list a while ago; every default property must be defined through a valid JSONSchema, any other attributes really shouldn't be added. Also correct the example in this docstring along the way, correctly quoting the key and adding `optional => 1` in order not to suggest anything that is advised against in the new paragraph further below. Signed-off-by: Max R. Carrara --- src/PVE/SectionConfig.pm | 18 ++++++++++++++++-- 1 file changed, 16 insertions(+), 2 deletions(-) diff --git a/src/PVE/SectionConfig.pm b/src/PVE/SectionConfig.pm index 6ad8772..71a0019 100644 --- a/src/PVE/SectionConfig.pm +++ b/src/PVE/SectionConfig.pm @@ -138,9 +138,10 @@ More precisely, this method returns a hash with the following structure: optional => 1, description => 'example property', }, - some-property => { - description => 'another example property', + 'some-property' => { type => 'boolean' + optional => 1, + description => 'another example property', }, }, options => { @@ -204,6 +205,19 @@ plugin architecture upfront, for example: Additional properties defined in I are stored in the C key. See Cproperties() >>>. +B It is advised to mark all default properties in C as +optional using C<< optional => 1 >>, with only very few exceptions. One such +exception would be a property that you intend to use as unique identifier of a +section. In that case, ensure that you explicitly define it with +C<< optional => 0 >> and that it is not used in any child plugins' +Coptions() >>> method. + +B When specifying the default properties in the C key, you +MAY only add attributes related to C> to property +definitions. Any other attributes, even those specific to C +(like C), are not considered valid. All properties in C +MUST be defined through a valid JSONSchema. + =cut sub private { -- 2.47.3 _______________________________________________ pve-devel mailing list pve-devel@lists.proxmox.com https://lists.proxmox.com/cgi-bin/mailman/listinfo/pve-devel