Clarify parameter defaults guidance in bgtm and style guide#394
Merged
Conversation
9dd5989 to
9154cfa
Compare
tuxmea
approved these changes
Jul 9, 2026
Both pages left module authors unsure where parameter defaults belong, which caused confusion in module reviews: static values duplicated in both init.pp and module Hiera data, and parameters declared Optional that always receive a value from Hiera. - bgtm.md: add a "Parameter defaults" subsection under Parameters covering static-vs-OS-specific placement, the one-home rule, and Optional[T] = undef usage, with a cross-link to the style guide. - style_guide.markdown: split "Parameter defaults" into static (inline in init.pp) and OS-specific approaches. The OS-specific example keeps the common value inline and overrides only the deviating OS through automatic parameter lookup, so authors add Hiera data for the exceptions rather than every supported OS. Cites puppet-chrony as a real-world reference, clarifies that common.yaml is not the home for parameter defaults, and adds guidance on keeping each default in one place and on Optional parameters. - style_guide.markdown: reconcile the pre-existing myservice class-layout example, which previously placed a static service_ensure default in common.yaml, by moving that default inline to match the new guidance. Closes OpenVoxProject#216 Signed-off-by: Michael Harp <[email protected]>
Illustrate the "Optional parameters" guidance with chrony's smoothtime parameter: declared Optional[String] = undef, and emitted in the config template only when a value is set, so undef genuinely means the optional feature is off. Signed-off-by: Michael Harp <[email protected]>
From the sig-documentation discussion on inline vs Hiera defaults: - Note the readability argument for inline defaults: when defaults live only in Hiera, a reader of init.pp can't tell whether a parameter has a default elsewhere or must be supplied. - Add the required-parameter case to the Optional guidance: when a value is genuinely required with no sensible default, give the parameter no default at all so compilation fails clearly, rather than papering over the requirement with Optional[T] = undef. Signed-off-by: Michael Harp <[email protected]>
9154cfa to
bb76142
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Problem
The parameter defaults guidance in
bgtm.html#parametersandstyle_guide.html#parameter-defaultswas unclear and inconsistent, which causedconfusion in module reviews (raised in VoxPupuli IRC).
bgtmsaid nothing aboutwhere defaults should live, and the style guide recommended module Hiera data
without distinguishing static cross-OS values from OS-specific ones, or
explaining when
Optional[T] = undefis appropriate. The result: modules withthe same static default duplicated in both
init.ppanddata/common.yaml, andparameters declared
Optionalthat always receive a value from Hiera.Changes
bgtm.md— new "Parameter defaults" subsection under Parameters coveringstatic-vs-OS-specific placement, the one-home rule, and
Optional[T] = undefusage, with a cross-link to the style guide.
style_guide.markdown— "Parameter defaults" split into static(inline in
init.pp) and OS-specific approaches. The OS-specific examplekeeps the common value inline and overrides only the deviating OS through
automatic parameter lookup, so authors add Hiera data for the exceptions
rather than for every supported OS. Adds a real-world reference to
puppet-chrony, clarifies that
common.yamlis not the home for parameter defaults under this guidance, andadds "keep each default in one place" and "Optional parameters" guidance.
style_guide.markdown— reconciled the pre-existingmyserviceclass-layout example, which previously placed a static
service_ensuredefault in
common.yaml, by moving that default inline so the whole page isinternally consistent.
Notes
The static-defaults-inline recommendation follows the
VoxPupuli PR review guide and stays
compatible with upstream puppet-strings, which still can't read
common.yamldefaults (puppet-strings#250).
OpenVox's openvox-strings
can now render
common.yamldefaults, and the docs note this, but keeping staticdefaults inline works with both toolchains.
Closes #216