Skip to content

Clarify parameter defaults guidance in bgtm and style guide#394

Draft
miharp wants to merge 1 commit into
OpenVoxProject:masterfrom
miharp:docs/parameter-defaults-216
Draft

Clarify parameter defaults guidance in bgtm and style guide#394
miharp wants to merge 1 commit into
OpenVoxProject:masterfrom
miharp:docs/parameter-defaults-216

Conversation

@miharp

@miharp miharp commented Jul 7, 2026

Copy link
Copy Markdown
Contributor

Problem

The parameter defaults guidance in bgtm.html#parameters and
style_guide.html#parameter-defaults was unclear and inconsistent, which caused
confusion in module reviews (raised in VoxPupuli IRC). bgtm said nothing about
where 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] = undef is appropriate. The result: modules with
the same static default duplicated in both init.pp and data/common.yaml, and
parameters declared Optional that always receive a value from Hiera.

Changes

  • bgtm.md — new "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 — "Parameter defaults" split 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 for every supported OS. Adds a real-world reference to
    puppet-chrony, clarifies that
    common.yaml is not the home for parameter defaults under this guidance, and
    adds "keep each default in one place" and "Optional parameters" guidance.
  • style_guide.markdown — reconciled the pre-existing myservice
    class-layout example, which previously placed a static service_ensure
    default in common.yaml, by moving that default inline so the whole page is
    internally 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.yaml
defaults (puppet-strings#250).
OpenVox's openvox-strings
can now render common.yaml defaults, and the docs note this, but keeping static
defaults inline works with both toolchains.

Closes #216

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 <mike@mikeharp.com>
@miharp miharp requested a review from a team as a code owner July 7, 2026 11:51
@miharp miharp marked this pull request as draft July 7, 2026 11:54
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Clarify parameter defaults guidance in bgtm and style guide

1 participant