snippets2changelog

Generate a changelog from individual snippets

General

Create version info files based on the latest changelog entry.

• Installation
• Usage
  • Info
  • Create
    • Snippet
    • Changelog
  • Parse
  • CI
    • GitHub
      • Actions
      • Custom workflow
    • Other
• Contributing
  • Setup
  • Testing
  • Changelog
• Credits

Installation

[<PYTHON> -m] pip[3] install [--user] [--upgrade] snippets2changelog

Usage

Info

Print informations about snippets2changelog

changelog-generator info

Create

Snippet

Create a new snippet with the given name at the specified snippets folder

changelog-generator create example_snippets/123.md

Short description: My example snippet
Choose from: ['bugfix', 'feature', 'breaking']
Type of change: feature
Choose from: ['internal', 'external', 'all']
Scope of change: external
Affected users (default all): testers

## My example snippet
<!--
type: feature
scope: external
affected: testers, users
-->

TBD

Changelog

Create or update a changelog with all snippets.

The generated changelog will be named <OLD_CHANGELOG_NAME.new> unless the --in-place flag is used. This flag is intended for CI usage with a clean checkout before a run.

Be aware to restore the changelog before another run as it might generate version entries and version bumps multiple times otherwise.

changelog-generator changelog changelog.md --snippets=.snippets [--in-place]

To just get the latest changelog entry without updating or generating the changelog, use --dry-run to print the latest snippet content in JSON format.

{
    "version": "1.5.0",
    "timestamp": "2024-10-12T13:36:46+02:00",
    "meta": {
        "type": "feature",
        "scope": [
            "all"
        ],
        "affected": [
            "all"
        ]
    },
    "content": "\n\nUse `--dry-run` with the `changelog` subparser to print the latest changelog entry as JSON instead of updating the changelog file.\n",
    "version_reference": "https://github.com/brainelectronics/snippets2changelog/tree/1.5.0"
}

The option --no-internal ignores all snippets with scope internal during the changelog generation. This is useful if those changes are not affecting the "product" like internal documentation changes or similar things, which e.g. do not require a deployment.

The option --version-reference allows to configure the URL to the tags in the rendered changelog file. Use e.g. https://github.com/<GITHUB_USER>/<PROJECT_USING_SNIPPETS2CHANGELOG>/tree/ for a project using this package.

Parse

Parse an existing snippet file and return the data as JSON without indentation

changelog-generator parse example_snippets/123.md \
  --indent=4

{
    "type": "feature",
    "scope": [
        "external"
    ],
    "affected": [
        "testers",
        "users"
    ],
    "title": "My example snippet",
    "details": "\n\nTBD\n"
}

CI

To use this tool in a CI environment use the following commands, job configs or actions.

GitHub

Actions

See changelog-from-snippets action.

Custom workflow

---
name: Generate changelog

on:
  push:
    branches:
      - main

jobs:
  changelog:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4
        with:
          # all history is needed to crawl it properly
          fetch-depth: 0
      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: '3.11'
      - name: Install
        run: |
          pip install snippets2changelog
      - name: Update changelog with snippets
        run: |
          changelog-generator \
            changelog changelog.md \
            --snippets=.snippets \
            --in-place \
            --no-internal

Other

pip install snippets2changelog
changelog-generator \
  changelog changelog.md \
  --snippets=.snippets \
  --in-place \
  --no-internal

Contributing

Setup

For active development you need to have poetry and pre-commit installed

# Python 3.9 compability is dropped with Poetry 2.3.0
python3 -m pip install --upgrade --user "poetry>2.2.0,<2.3.0" "pre-commit>=4.5.1,<5"
git clone https://github.com/brainelectronics/snippets2changelog.git
cd snippets2changelog
pre-commit install
poetry install
# poetry update --lock

Testing

# run all tests
poetry run coverage run -m pytest -v

# run only one specific tests
poetry run coverage run -m pytest -v -k "test_read_save_json"

Generate the coverage files with

python create_report_dirs.py
coverage html

The coverage report is placed at reports/coverage/html/index.html

Changelog

The changelog format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

Please add a changelog snippet, see above, for every PR you contribute. The changes are categorised into:

• bugfixes fix an issue which can be used out of the box without any further changes required by the user. Be aware that in some cases bugfixes can be breaking changes.
• features is used to indicate a backwards compatible change providing improved or extended functionalitiy. This does, as bugfixes, in any case not require any changes by the user to keep the system running after upgrading.
• breaking creates a breaking, non backwards compatible change which requires the user to perform additional tasks, adopt his currently running code or in general can't be used as is anymore.

The scope of a change shall either be:

• internal if no new deployment is required for this change, like updates in the documentation for example
• external or all if this change affects the public API of this package or requires a new tag and deployment for any other reason

The changelog entry shall be short but meaningful and can of course contain links and references to other issues or PRs. New lines are only allowed for a new bulletpoint entry. Usage examples or other code snippets should be placed in the code documentation, README or the docs folder.

Credits

A big thank you to the creators and maintainers of SemVer.org for their documentation and regex example