--- ---

Product Change Tracking and Documentation

Integration and deployment/delivery process for DocOps Lab sites and artifacts.

All DocOps Lab products use DocOps Lab’s ReleaseHx utility to generate release notes and changelogs.

However, each product implements ReleaseHx in a customized manner, so always refer to any given project’s documentation for specific protocols. Check for a file like docs/content/_doc/release-history-management.adoc file or else fall back to README.adoc (search for ReleaseHx).

Product Contributor Documentation Responsibilities

Each contributor of product code or docs changes is responsible for preparing that change to be included in release documentation, when applicable.

GitHub Issues Labels

GitHub Issues are use specific labels to indicate documentation expectations.

needs:docs

The issue requires documentation updates as part of its resolution. Documentation updates will likely be in a sub-issue with a documentation label.

needs:note

The issue requires a note in the release history when resolved. Release notes are appended to the description body under ## Release Note.

changelog

The issue summary should be included in the changelog for the next release, even if no release note is included.

Issues labeled changelog will automatically appear in the Changelog section of the Release History document. Release notes must be manually entered.

Change Documentation

When a change to the product affects user-facing functionality, the documentation needs to change.

For early product versions, most documentation appears in the root README.adoc file. When a product has a docs/content/ path, documentation changes usually have a home in an AsciiDoc (.adoc) file in a subdirectory.

Reference matter should be documented where it is defined, such as in specs/data/*.yml files.

Release Note Entry

User-facing product changes that deserve explanation (not just notice) require a release note.

Add a release note for a given issue by appending it to the issue body following a ## Release Note heading.

Example
## Release Note

The content of the release note goes here, in Markdown format.
Try to keep it to one paragraph with minimal formatting.

Release History Document Creation

ReleaseHx automatically generates release notes and changelogs from GitHub Issues and PRs when properly labeled.

Every DocOps Lab project implements ReleaseHx differently as a way of “eating our own dog food”.

Refer to any given project’s documentation for specific instructions on how to prepare changes for inclusion in release notes and changelogs.

The general procedure is as follows:

  1. Generate a draft release history in YAML.

    bundle exec rhx <version> --yaml --fetch

  2. Edit the generated YAML to ensure clarity and completeness.

  3. Generate the Markdown version.

    bundle exec rhx <version> --md docs/release/<version>.md