Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
139 lines (99 loc) · 5.44 KB

CONTRIBUTING.md

File metadata and controls

139 lines (99 loc) · 5.44 KB
Raw

Contributing to OpenVox Documentation

We welcome community contributions to the OpenVox documentation! You can help by reporting errors and typos, or by contributing new or updated content.

Reporting issues

File a GitHub issue to report errors, inaccuracies, or gaps in the documentation. Include:

  • The URL of the affected page
  • A description of what is wrong or missing
  • Your best understanding of what the documentation should say

Contributing changes

Contributions are made via GitHub pull requests.

  1. Fork the repository and create a branch from master
  2. Make your changes (see Previewing locally below)
  3. Commit with a GPG signature and DCO sign-off: git commit -S -s
  4. Open a pull request against master
  5. Ensure CI is passing and your branch is up to date with master before marking ready for review

All commits must be:

  • GPG-signed (-S): configure a signing key with git config user.signingkey YOUR_KEY_ID and git config commit.gpgsign true
  • DCO signed-off (-s): certifies your contribution under the Developer Certificate of Origin

The Signed-off-by trailer must match your Git identity:

Signed-off-by: Your Name <your@email.com>

Previewing locally

Ruby 3.2 or later is required. With rbenv or rvm installed:

bundle install
bundle exec jekyll serve

The site is available at http://localhost:4000. Navigation changes require updating the matching file in _data/nav/. The documentation itself is in docs folder with a subfolder for each component and version.

For a complete set of the documentation, the autogenerated references must be added:

bundle exec rake references:openvox INSTALLPATH=docs
bundle exec rake references:openfact INSTALLPATH=docs
bundle exec rake references:openbolt INSTALLPATH=docs

Or build every pinned product/version at once — this is what CI does, reading the pins from _data/products.yml:

bundle exec rake references:all INSTALLPATH=docs

Note: It is possible to specify a version (tag or branch) to be used. If no version is provided, the latest stable release tag will be used. This is useful when checking for changes made in upstream reference source like OpenFact or OpenBolt repo itself.

bundle exec rake references:openvox INSTALLPATH=docs VERSION=main
bundle exec rake references:openfact INSTALLPATH=docs VERSION=main
bundle exec rake references:openbolt INSTALLPATH=docs VERSION=main

By default the references are built into each product's current stable collection (e.g. _openvox_latest). Use COLLECTION to target a specific version's directory, for example when regenerating a frozen older major from its matching upstream tag:

bundle exec rake references:openvox INSTALLPATH=docs VERSION=8.27.0 COLLECTION=_openvox_8x

To build every pinned product/version in one go — the same way CI does — use references:all, which reads the version/tag pins from _data/products.yml (it does not take VERSION or COLLECTION):

bundle exec rake references:all INSTALLPATH=docs

Writing guidelines

Naming of OpenVox and Puppet

  • OpenVox is used when referring to the community implementation of Puppet DSL
  • Puppet is used when describing the underlying DSL or the ecosystem as a whole

Use the following terms for the individual components:

  • OpenVox Server
  • OpenVoxDB
  • OpenFact
  • OpenBolt

Writing and editing pages

  • Prefer editing existing pages over creating new ones
  • Each page should cover a single subject area
  • Focus on helping people solve problems and get things done; avoid excessive background
  • Use numbered lists for sequential steps; state prerequisites upfront and the outcome at the end
  • Provide command or code examples for common scenarios
  • Link to related documentation

Tone

  • Be friendly and authoritative
  • Use simple, direct language; avoid passive voice
  • Be concise, but not terse
  • Use second person: "Open the file in your editor"
  • Use inclusive, gender-neutral language
  • Avoid patronizing words like clearly, actually, or obviously

Grammar and spelling

  • Follow the Google developer documentation style guide for general conventions
  • Use American English spelling: color, specialize
  • Use the serial comma: "... supported on Unix, Linux, and Windows"
  • Avoid idioms or metaphors that may not translate across languages and cultures

Formatting

  • File names and paths: monospace
  • Commands and code: monospace; short commands inline, longer blocks in fenced code blocks with a language identifier (console, yaml, text, etc.)
  • Use console for commands to run in a terminal; use bash or puppet for scripts and manifests

Linking

  • Within a versioned collection (e.g. docs/_openvox_8x/), use relative links (page.html) rather than absolute /openvox/latest/page.html links. Absolute /latest/ links silently cross version boundaries when a new major version is added.
  • Prefer page.html over ./page.html — the leading ./ is unnecessary.
  • When linking across collections (e.g. from _openvox_8x/ to _openvoxdb_8x/), use absolute paths (/openvoxdb/latest/page.html).
  • Use full URIs for external links only.