DOCSEARCHbyAlgolia
Submit Docs

Keep a Changelog Documentation

repository·main·Indexed 27 days ago

https://github.com/olivierlacan/keep-a-changelog

Guidelines for generating and maintaining human-readable changelogs. The standard promotes organized change histories using six canonical categories: Added, Changed, Deprecated, Removed, Fixed, and Security, moving away from automated git log dumps to ensure documentation is written for humans.

Tokens
10.1K
Snippets
13
Records
53
Agent score
92%

What's inside Keep a Changelog

  2. Review sector adoption of Keep a Changelog

    main

    The docs/2.0.0-adoption-sectors.md file provides a verifiable list of organizations and projects that either use the Keep a Changelog (KAC) format in their CHANGELOG files or explicitly recommend it in their documentation (e.g., CONTRIBUTING guides or engineering handbooks).

    Adoption is categorized into four sectors:

    1. Governments / public sector: Includes entities like The National Archives (UK) which mandates KAC in their engineering handbook, and CMS (U.S.) which recommends it in CONTRIBUTING.md.
    2. Non-profits / foundations: Includes the Wikimedia Foundation (which recommends KAC conventions in CONTRIBUTING.md) and the CNCF.
    3. Major open-source projects: Includes high-star projects like Textualize/Rich, Textualize/Textual, and encode/HTTPX.
    4. Large companies: Includes Microsoft (with significant org-wide footprint), Google, GitHub, Cloudflare, Shopify, and HashiCorp.

    Note on signals:

    • USE: The organization's CHANGELOG file carries the KAC format/header.
    • RECOMMEND: The organization's documentation (handbooks, style guides) instructs contributors to follow the KAC standard.

  3. Project History and Version Milestones

    main

    Key historical milestones for the Keep a Changelog project:

    • 2014-05-31: Repository created by Olivier Lacan.
    • 2015-02-16: First notable press coverage in WP Tavern.
    • 2017-06-20: Release of v1.0.0, which introduced the Guiding Principles (including the 'for humans' principle) and the six standard change types.
    • 2019-02-15: Release of v1.1.0.
    • 2023-03-05: Release of v1.1.1.

    The project is currently translated into 28 languages.

  5. Best practices for automation and LLMs

    main

    When using automation, CI, or Large Language Models (LLMs) to assist with changelogs, follow these principles:

    • Human Curation: Machines can draft entries, but humans must curate them. A generated changelog should be treated as a draft, not a final product.
    • No Machine-Only Format: There is no separate machine-readable format; the human-readable CHANGELOG.md is the source of truth for both humans and tools.
    • Conventional Commits: Use tools like Conventional Commits to generate drafts, but ensure the output is refined for readability.
    • CI Integration: Use CI to handle the mechanics of the changelog (e.g., version bumping or drafting), but do not use it as a hard gate that prevents releases if the changelog is imperfect.

  6. Follow the Keep a Changelog tone and voice principles

    main

    When writing changelogs or documentation following the Keep a Changelog standard, adhere to these eight core principles to ensure content is accessible to non-native English speakers and non-programmers:

    1. Lead with the point: State the recommendation first, then the reason.
    2. Don't gatekeep: Avoid words that imply knowledge is assumed, such as obvious, simply, just, of course, trivially, everyone knows, or as you'd expect.
    3. Plain over clever: Avoid idioms, metaphors, wordplay, and cultural references.
    4. Explain necessary jargon; drop the rest: Use common technical terms but define them briefly upon first use. Prefer plain verbs (e.g., release instead of ship; formatted correctly instead of well-formed).
    5. Short sentences: Aim for one idea per sentence using the active voice.
    6. Concise over complete: Remove redundant words or paragraphs that repeat existing points.
    7. Consistent terms: Use the same word for the same concept every time (e.g., always use changelog, entry, version, or release).
    8. Warm, not in-group: Use a friendly tone that does not rely on insider jokes or references that exclude outsiders.

  7. Implement version-pinned changelog views via derivation

    main

    To ensure that older specification pages display a changelog consistent with their era (rather than the latest version's format), use a derivation approach. Instead of maintaining separate files for every version, compute a 'pinned' view from the single live CHANGELOG.md at build time.

    Derivation Logic

    When a page's major.minor track is older than the newest track documented in CHANGELOG.md, the following transformations are applied to the view:

    1. Identify Cutoff: The pin cutoff is the newest release on the page's major.minor track. Patch releases are ignored for the cutoff to allow for site fixes/translations without shifting the spec version.
    2. Filter Entries: All entries newer than the cutoff are removed, along with their corresponding reference-link definitions.
    3. Handle Unreleased: The [unreleased] section heading is preserved (to maintain format consistency), but its contents are emptied.
    4. Rewrite Links:
      • The [unreleased] compare link is rewritten to diff against the cutoff release.
      • The "based on Keep a Changelog" URL in the preamble is rewritten to point to the specific spec version for that page.
    5. Update Caption: The caption above the example is updated to state the changelog is shown "as of the last x.y release".

  8. Integrate KAC with Conventional Commits and automation

    main

    Keep a Changelog is designed to be complementary to automation tools like semantic-release, release-please, Changesets, or git-cliff.

    • Automation/Commits: These tools operate on the input (the commit history).
    • KAC: This is the human-facing output.

    Treat automated changelogs as a draft. The final step in a professional workflow is human curation to ensure the document is readable and focuses on notable changes rather than a raw git log dump.

  9. Set up the CHANGELOG.md file header

    main

    Name your file CHANGELOG.md. Start the file with a # Changelog heading and a preamble that explains the file's purpose and the conventions followed (e.g., Keep a Changelog and Semantic Versioning).

    # Changelog

All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/2.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

  10. Attribute changes to contributors

    main

    While not explicitly mandated by the core Keep a Changelog (KAC) spec, many projects use contributor attribution to credit developers. There are two common styles:

    1. GitHub-style machine-generated attribution: Using a handle and PR link (e.g., by @user in [#123]). Note that @user handles are host-specific (e.g., GitHub-only).
    2. Manual attribution: Using a real name in parentheses (e.g., (Real Name)).

    When using handles, ensure you also include a link to the PR or issue to maintain portability.

    Fix log accumulation across DynamicData test invocations by @Evangelink in [#7925]

Less_Parser: Fix SetImportDirs() type hint... (Timo Tijhof)

  12. Set up semantic triage with LaBSE model

    main

    For meaning-based errors that linting cannot catch, you can set up a semantic triage pipeline using the LaBSE model. This requires a one-time setup to create a local virtual environment and download the ~1.8 GB model.

    Setup Commands:

    • Use bin/rake translations:setup or tools/setup.sh to install dependencies and download the model to your standard Hugging Face cache (~/.cache/huggingface).
    • To keep the model project-local, set the HF_HOME environment variable.

    Running Triage:

    • Use bin/rake translations:qa to run the entire pipeline (export segments $\rightarrow$ score with LaBSE).
    • Alternatively, export segments manually using --segments and run the Python script tools/labse_triage.py directly.