Skip to content

Clarify parameter defaults guidance in bgtm and style guide #216

@miharp

Description

@miharp

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

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions