Skip to content

Latest commit

 

History

History
46 lines (28 loc) · 3.35 KB

CONTRIBUTING.md

File metadata and controls

46 lines (28 loc) · 3.35 KB
Raw

Thank you for helping us improve our docs! Here are some non-obvious things you might need to know when committing to this repo:

  • Beware of source/references/VERSION
  • MCollective doesn't live here
  • PuppetDB doesn't live here

Please Don't Do Drive-by Edits to Anything In source/references/VERSION

These files are all automatically generated from strings in the Puppet source code. If you edit the old frozen versions, we will generate a fresh page of "wrong" text when the next version of Puppet comes out!

Instead, please edit the text in the Puppet source code (see below for a list of locations) and submit a pull request to the Puppet project. Be careful about quoting and escaping, and be sure to read Puppet's contributing guidelines. For minor docs edits, you can skip filing a JIRA ticket and instead begin your commit message with (docs).

Locations of Docs Text in the Puppet Source

  • For configuration.html, look in lib/puppet/defaults.rb.
  • For function.html, look in lib/puppet/parser/functions/NAME.rb.
  • For indirection.html, look in lib/puppet/indirector/INDIRECTION/TERMINUS.rb.
  • For metaparameter.html, look in lib/puppet/type.rb and search for newmetaparam(:NAME).
  • For report.html, look in lib/puppet/reports/NAME.rb.
  • For type.html, look in lib/puppet/type/NAME.rb or lib/puppet/provider/NAME/PROVIDER.rb.
    • If you find something wrong with the provider features (the big tables with Xs in them), please just file a bug report instead; fixing them is kind of complicated.

Should I Also Edit the Old Frozen Versions?

Only sometimes. Most of our readers only care about the most recent version in the release series they're using.

  • If you're fixing an error that could actually ruin someone's day, that's pretty important! We would love a patch to the old versions.
  • If it's just a "nice to have" fix that clarifies something confusing, please don't patch everything back to 0.24.5. We would love a patch to just the most recent versions in the current and maintenance release series.

MCollective Docs Don't Live Here

The MCollective docs live in the website directory in the main MCollective GitHub repo; whenever we update docs.puppetlabs.com, we pull in the latest content from the master branch. Please submit pull requests there.

The navigation sidebar DOES live here, at source/_includes/mcollective_menu.html.

PuppetDB Docs Don't Live Here... Anymore

Although we host the PuppetDB 0.9 and 1.0 manuals, the docs for version 1.1 and later were moved into the documentation directory in the main PuppetDB GitHub repo. Whenever we update docs.puppetlabs.com, we pull in the latest content from the 1.1.x, 1.2.x, etc. branches.

To edit the PuppetDB docs, submit a pull request to the earliest major.minor.x branch that has the problem you're trying to fix. In your pull request message, you should request that the change be merged forward.

The navigation sidebars DO live here, at source/_includes/puppetdb<VERSION>.html.

Should I Also Edit the 0.9/1.0 Docs?

Your call, but we generally don't, as those versions aren't widely used anymore. If you do, please link to your PuppetDB pull request in your commit message.