From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from firstgate.proxmox.com (firstgate.proxmox.com [212.224.123.68]) by lore.proxmox.com (Postfix) with ESMTPS id B316A1FF145 for ; Thu, 05 Feb 2026 16:20:40 +0100 (CET) Received: from firstgate.proxmox.com (localhost [127.0.0.1]) by firstgate.proxmox.com (Proxmox) with ESMTP id CC36614FE3; Thu, 5 Feb 2026 16:21:13 +0100 (CET) From: Stoiko Ivanov To: pmg-devel@lists.proxmox.com Subject: [PATCH pmg-docs] gen-pmg.conf.5: check key to section mapping only in docs build Date: Thu, 5 Feb 2026 16:20:24 +0100 Message-ID: <20260205152029.437975-1-s.ivanov@proxmox.com> X-Mailer: git-send-email 2.47.3 MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Bm-Milter-Handled: 55990f41-d878-4baa-be0a-ee34c49e34d2 X-Bm-Transport-Timestamp: 1770304758852 X-SPAM-LEVEL: Spam detection results: 0 AWL 0.069 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 RCVD_IN_VALIDITY_CERTIFIED_BLOCKED 0.001 ADMINISTRATOR NOTICE: The query to Validity was blocked. See https://knowledge.validity.com/hc/en-us/articles/20961730681243 for more information. RCVD_IN_VALIDITY_RPBL_BLOCKED 0.001 ADMINISTRATOR NOTICE: The query to Validity was blocked. See https://knowledge.validity.com/hc/en-us/articles/20961730681243 for more information. RCVD_IN_VALIDITY_SAFE_BLOCKED 0.001 ADMINISTRATOR NOTICE: The query to Validity was blocked. See https://knowledge.validity.com/hc/en-us/articles/20961730681243 for more information. SPF_HELO_NONE 0.001 SPF: HELO does not publish an SPF Record SPF_PASS -0.001 SPF: sender matches SPF record Message-ID-Hash: 2CBMQPHGU6LFD2DALDFZRMZTV57P6MM7 X-Message-ID-Hash: 2CBMQPHGU6LFD2DALDFZRMZTV57P6MM7 X-MailFrom: s.ivanov@proxmox.com X-Mailman-Rule-Misses: dmarc-mitigation; no-senders; approved; loop; banned-address; emergency; member-moderation; nonmember-moderation; administrivia; implicit-dest; max-recipients; max-size; news-moderation; no-subject; digests; suspicious-header X-Mailman-Version: 3.3.10 Precedence: list List-Id: Proxmox Mail Gateway development discussion List-Help: List-Owner: List-Post: List-Subscribe: List-Unsubscribe: adding a new option to pmg.conf currently requires updating pmg-docs, as both are tightly coupled through gen-pmg.conf.pl. The checks in gen-pmg.conf.pl ensure that most keys (some are explicitly ignored) are put in a category to be rendered in the fitting section of the docs. While ensuring our docs are consistent makes sense, the mutual dependency of pmg-api and pmg-docs slows down things like `sbuild`, or rolling out fixes for older releases - as it requires an update of pmg-docs-generator before upgrading pmg-api. The patch reverses the logic of: f475c3f ("gen-pmg.conf.5: allow to overwrite undocumented key error for bootstrapping") by not dying in the default case. Ensuring that each config key is in a category happens when building pmg-docs - by setting the PMG_DOCS_IGNORE_MISSING_KEY explicitly to 0 in the Makefile. tested by removing an existing key from gen-pmg.conf.5-opts.pl, and building pmg-api, followed by building pmg-docs, which failed. the pmg.conf(5) manpage still had the key present. Signed-off-by: Stoiko Ivanov --- Makefile | 2 ++ gen-pmg.conf.5-opts.pl | 4 +++- 2 files changed, 5 insertions(+), 1 deletion(-) diff --git a/Makefile b/Makefile index 52980a6..6031ef6 100644 --- a/Makefile +++ b/Makefile @@ -15,6 +15,8 @@ DOC_DEB=$(DOC_PACKAGE)_$(DEB_VERSION_UPSTREAM_REVISION)_all.deb export SOURCE_DATE_EPOCH ?= $(shell dpkg-parsechangelog -STimestamp) SOURCE_DATE_HUMAN := $(shell date -d "@$(SOURCE_DATE_EPOCH)") +# ensure all pmg.conf keys are accounted for in their respective section. +export PMG_DOCS_IGNORE_MISSING_KEY ?= 0 all: index.html diff --git a/gen-pmg.conf.5-opts.pl b/gen-pmg.conf.5-opts.pl index 3ef9d98..2684719 100755 --- a/gen-pmg.conf.5-opts.pl +++ b/gen-pmg.conf.5-opts.pl @@ -75,6 +75,8 @@ my $key_groups = { }], }; +my $die_on_missing = !( $ENV{PMG_DOCS_IGNORE_MISSING_KEY} // 1); + if (1) { # verify if we document all mail settings my $plugin = PMG::Config::Base->lookup('mail'); @@ -98,7 +100,7 @@ if (1) { next if $k =~ m/^max_(filters|policy|smtpd_in|smtpd_out)$/; if (!defined($found_mail_keys->{$k})) { - die "undocumented key '$k'" if !$ENV{PMG_DOCS_IGNORE_MISSING_KEY}; + die "undocumented key '$k'" if $die_on_missing; warn "WARNING: undocumented key '$k'\n"; } } -- 2.47.3