puppetlabs / puppetlabs/puppet-strings

Plan parameter index may link to wrong parameter when there are duplicates

Open
#294 2 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

bug
Dominant language
Ruby
Stars
90
Forks
90
PR merge metrics
No merged PRs in 30d

Description

Describe the Bug

The generated markdown documentation for a Puppet plan includes an indexed list of plan parameters that link to parameter entries describing each one. If a parameter has the same name across multiple plans or tasks, the index appears to always link to just the parameter name and therefore to just the first instance of where that parameter is first referenced, which may be in another task or plan.

Expected Behavior

Plan parameter index should link to the plan's parameter references.

Steps to Reproduce

You can see this in a generated REFERENCE.md page from pam_tools.
The puppetlabs::teardown plan has a scaledown_timeout parameter. The link in the parameter list links to the parameter under the delete_k8s_app_resources task instead.

Environment

  • Version 2.9.0
  • Platform Ubuntu 18.04

Additional Context

Add any other context about the problem here.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by generating the markdown documentation for the pam_tools example and inspect the puppetlabs::teardown parameter index alongside the delete_k8s_app_resources task entry. Trace how duplicate parameter names are turned into links, then verify that the plan index points to its own parameter reference rather than the first matching name.

Written by the indexing model from the issue text.

Assessment

Tech stack
ruby
Domain
documentation
Issue type
Bug
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.