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.

When a product matures (prior to 1.0), the documentation should move into new paths, separated depending on whether it is user-facing or internal.

In either case, the way to discover where to put documentation changes is to use a docopslab-dev skim task on the existing docs source. These skims are semantic outlines of the source files in their converted state. They can be used for navigation, content discovery, and change impact analysis.

User-Facing Documentation

End-user docs, including API documentation, is usually sourced in docs/content/, alongside asset files for the documentation site (images, CSS, etc.).

The docs/ path is typically a Jekyll site’s source path, but in most cases a pre-build operation will generate supplemental files in docs/built/ or the like.

If the changes you are documenting are user-facing, use the tasks below to determine where the relevant documentation lives.

Skim the docs

bundle exec rake labdev:skim:adoc[README.adoc,tree,json] > .agent/docs/readme.json
bundle exec rake labdev:skim:adoc[docs/,tree,json] > .agent/docs/skim-docs.json

Internal Documentation

Generally speaking, internal documentation (for developers, maintainers, and their AI agents), belongs in _docs/ and .agent/docs/ paths.

The _docs/agent/ path is for overlays that take priority over parallel docs in .agent/docs/ (maintained by docopslab-dev library syncing).

Skim the README

bundle exec rake labdev:skim:adoc[README.adoc,tree,json] > .agent/docs/readme.json

Skim the internal docs

bundle exec rake labdev:skim:adoc[_docs/,tree,json] > .agent/docs/skim-internal.json

Skim the agent docs to see if any overlay is needed

bundle exec rake labdev:skim:md[.agent/docs/:_docs/agent/,tree,json] > .agent/docs/skim-agent.json

If a local instruction contradicts or differs arbitrarily from the main DocOps Lab developer/contributor docs, create an overlay file in _docs/agent/* with the same sub-path and filename.

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:

Generate a draft release history in YAML.
```
bundle exec rhx <version> --yaml --fetch
```
Edit the generated YAML to ensure clarity and completeness.

Generate the Markdown version.

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