[pve-devel] [PATCH pve-common v1 00/23] Document PVE::SectionConfig Peculiarities

[Max R. Carrara]

Document PVE::SectionConfig Peculiarities - v1
==============================================

This was a long overdue series that adds a bunch of unit tests and
documentation updates for PVE::SectionConfig. The main motivation for
this series is me running somewhat regularly into new discoveries when
using PVE::SectionConfig for other purposes or investigating how certain
schemas are generated.

Since there have been quite a few surprises and somewhat sharp corners,
I decided to document all of these "peculiarities" in the form of unit /
regression tests instead of lengthy, wordy, borderline incomprehensible
paragraphs in the PVE::SectionConfig POD. (Seriously, some behaviors are
quite hard to parse when written out as text.)

The additional benefit of these tests is that they (should) guard us
against any regressions, should we have to make changes to the
PVE::SectionConfig machinery at some point in the future. On top of
that, we could use them as reference for aligning the Perl and Rust
SectionConfig / JSONSchema implementations in the future.

The commits should hopefully explain everything in detail.

Note though that these tests are by no means exhaustive. The test
scripts are however designed in such a way that it should be relatively
simple to add new cases whenever a new quirk pops up.

Finally, the POD docstrings in the PVE::SectionConfig source are also
adapted / corrected / clarified etc., which was made possible by the
insights gained from writing all of these tests.

References
==========

[0]: https://lore.proxmox.com/pve-devel/20251121165858.818307-1-m.carrara@proxmox.com/

Summary of Changes
==================

Max R. Carrara (23):
  sectionconfig: remove unused variable in get_property_schema()
  tests: sectionconfig: add comparison test structure
  tests: sectionconfig: add test case for fixed props in updateSchema
  tests: sectionconfig: add case for unused properties
  tests: sectionconfig: add case for unused optional default properties
  tests: sectionconfig: add case for opt. default prop being req. once
  tests: sectionconfig: add case for opt. default prop requirde by all
  tests: sectionconfig: add case for unused required default properties
  tests: sectionconfig: add case for req. default prop being req. once
  tests: sectionconfig: add case for required default prop req. by all
  tests: sectionconfig: add case for required default props opt. for all
  tests: sectionconfig: add isolated mode test structure
  tests: sectionconfig: add case for an ident. prop on two plugins
  tests: sectionconfig: add case for same prop. w/ different optionality
  tests: sectionconfig: add case for differing opt. default prop uses
  tests: sectionconfig: add case for differing req. default prop uses
  sectionconfig: correct docs regarding global props in unified mode
  sectionconfig: reword docs regarding property usage in isolated mode
  sectionconfig: extend / correct docstring of `private()` method
  sectionconfig: note that a prop must be defined through a JSONSchema
  sectionconfig: note that props added by plugins are always optional
  sectionconfig: note that `createSchema()` is universal for all plugins
  sectionconfig: correct example in docstring of `updateSchema()`

 src/PVE/SectionConfig.pm                     |   62 +-
 test/Makefile                                |    5 +-
 test/SectionConfig/Helpers.pm                |  114 +
 test/SectionConfig/Makefile                  |   11 +
 test/SectionConfig/schema_comparison_test.pl | 2047 ++++++++++++++++++
 test/SectionConfig/schema_isolated_test.pl   |  826 +++++++
 6 files changed, 3047 insertions(+), 18 deletions(-)
 create mode 100644 test/SectionConfig/Helpers.pm
 create mode 100644 test/SectionConfig/Makefile
 create mode 100755 test/SectionConfig/schema_comparison_test.pl
 create mode 100755 test/SectionConfig/schema_isolated_test.pl

-- 
2.47.3