--- ---

Git Commits Style Guide

Protocols for authoring Git commits for DocOps Lab projects

General Style

DocOps Lab loosely follows the Conventional Commits specification for Git commit messages.

Enforcement is not strict, but using modified Conventional Commits style is encouraged for consistency and clarity.

Most DocOps Lab projects do not base Changelog/Release Notes generation on commit messages.

The basic outline for a Conventional Commit message is:

<type>[optional scope]: <subject>

[optional body]

[optional footer(s)]

Commit Subject

The commit subject is the text after <type>[optional scope]:. It should be concise and to the point, summarizing the change in 50 characters or less.

Start the subject with a capitalized imperative verb. For example, use “feat: Add widget” instead of “feat: add widget” or “feat: Added widget”.

Commit Types

  • create: Add installation guide for new docs or UI content

  • edit: Clarify setup notes for minor edits to docs or UI content

  • feat: Add widget for new features OR improvements

  • fix: Handle missing widget config for bugfixes

  • chore: Bump gem version for version bumps and sundry tasks with no product impact

  • test: Cover widget validation for test code changes

  • refactor: Extract widget parser for code restructuring with no functional changes

  • style: Format widget examples for formatting, missing semi-colons, etc; no functional changes

  • perf: Cache widget lookup for performance improvements

  • auto: Update release workflow for changes to CI/CD pipelines and build system

  • revert: Restore previous widget behavior for reverting previous changes

Commit Body Conventions

  • Use the body to explain what and why vs. how.

  • Reference issues and pull requests as needed.

  • Use bullet points (- text) and paragraphs as needed for clarity.

  • Do not hard-wrap lines, but do:

    • use 1-sentence per line

    • keep sentences short