Problem
The parameter defaults guidance in two pages is unclear and inconsistent,
leading to confusion in module reviews (raised in VoxPupuli IRC).
bgtm.html#parameters covers parameter naming and count but says nothing
about where defaults should live — inline in init.pp or in module hiera
data.
style_guide.html#parameter-defaults recommends module hiera data via
automatic parameter lookup but doesn't distinguish between static cross-OS
values and OS-specific values, doesn't mention the puppet-strings limitation,
and gives no guidance on when Optional[T] = undef is appropriate vs.
misleading.
The result: modules with the same static default value duplicated in both
init.pp and data/common.yaml, and parameters declared Optional that
always receive a value from hiera anyway.
What needs to be documented
Where defaults should live (confirmed by the VoxPupuli PR review guide):
- Static defaults identical across every supported OS → inline in the
parameter declaration in init.pp. Required because
puppet-strings#250
(still open) means defaults in data/common.yaml are invisible to
generated documentation.
- OS-specific defaults → module hiera data with a per-OS hierarchy.
- Don't duplicate the same value in both places.
Optional[T] = undef — appropriate only when undef is a genuine
runtime value (parameter controls an optional feature). Don't use it simply
to defer a default to Hiera when the parameter will always have a value.
Pages to update
docs/_openvox_8x/bgtm.md — add parameter defaults guidance under ### Parameters
docs/_openvox_8x/style_guide.markdown — expand ### Parameter defaults with the two-approach distinction, no-duplication rule, and Optional[T] guidance
Problem
The parameter defaults guidance in two pages is unclear and inconsistent,
leading to confusion in module reviews (raised in VoxPupuli IRC).
bgtm.html#parameterscovers parameter naming and count but says nothingabout where defaults should live — inline in
init.ppor in module hieradata.
style_guide.html#parameter-defaultsrecommends module hiera data viaautomatic parameter lookup but doesn't distinguish between static cross-OS
values and OS-specific values, doesn't mention the puppet-strings limitation,
and gives no guidance on when
Optional[T] = undefis appropriate vs.misleading.
The result: modules with the same static default value duplicated in both
init.ppanddata/common.yaml, and parameters declaredOptionalthatalways receive a value from hiera anyway.
What needs to be documented
Where defaults should live (confirmed by the VoxPupuli PR review guide):
parameter declaration in
init.pp. Required becausepuppet-strings#250
(still open) means defaults in
data/common.yamlare invisible togenerated documentation.
Optional[T] = undef— appropriate only whenundefis a genuineruntime value (parameter controls an optional feature). Don't use it simply
to defer a default to Hiera when the parameter will always have a value.
Pages to update
docs/_openvox_8x/bgtm.md— add parameter defaults guidance under### Parametersdocs/_openvox_8x/style_guide.markdown— expand### Parameter defaultswith the two-approach distinction, no-duplication rule, andOptional[T]guidance