gha-utils 4.11.0__tar.gz

gha_utils-4.11.0/PKG-INFO

@@ -0,0 +1,349 @@
+Metadata-Version: 2.2
+Name: gha-utils
+Version: 4.11.0
+Summary: ⚙️ CLI helpers for GitHub Actions + reuseable workflows
+Author-email: Kevin Deldycke <kevin@deldycke.com>
+Project-URL: Homepage, https://github.com/kdeldycke/workflows
+Project-URL: Repository, https://github.com/kdeldycke/workflows
+Project-URL: Funding, https://github.com/sponsors/kdeldycke
+Project-URL: Issues, https://github.com/kdeldycke/workflows/issues
+Project-URL: Changelog, https://github.com/kdeldycke/workflows/blob/main/changelog.md
+Keywords: build-automation,changelog-formatter,ci-cd,cli,formatting,github-actions,labels,linting,markdown,mypy,nuitka,packaging,pypi,python,release-automation,sphinx,sponsorship,terminal,typo,workflow-reusable,yaml
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Console
+Classifier: Framework :: Sphinx
+Classifier: Framework :: Pelican
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: GNU General Public License v2 or later (GPLv2+)
+Classifier: Operating System :: MacOS :: MacOS X
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: Programming Language :: Unix Shell
+Classifier: Topic :: Documentation :: Sphinx
+Classifier: Topic :: File Formats :: JSON
+Classifier: Topic :: Security
+Classifier: Topic :: Software Development :: Build Tools
+Classifier: Topic :: Software Development :: Compilers
+Classifier: Topic :: Software Development :: Documentation
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Topic :: Software Development :: Version Control :: Git
+Classifier: Topic :: System :: Archiving :: Packaging
+Classifier: Topic :: System :: Installation/Setup
+Classifier: Topic :: System :: Shells
+Classifier: Topic :: System :: Software Distribution
+Classifier: Topic :: Terminals
+Classifier: Topic :: Text Processing :: Markup :: HTML
+Classifier: Topic :: Text Processing :: Markup :: Markdown
+Classifier: Topic :: Utilities
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: backports.strenum~=1.3.1; python_version < "3.11"
+Requires-Dist: boltons>=24.0.0
+Requires-Dist: bump-my-version>=0.21.0
+Requires-Dist: click-extra~=4.11.0
+Requires-Dist: packaging~=24.1
+Requires-Dist: PyDriller~=2.6
+Requires-Dist: pyproject-metadata~=0.9.0
+Requires-Dist: tomli~=2.0.1; python_version < "3.11"
+Requires-Dist: wcmatch>=8.5
+Provides-Extra: test
+Requires-Dist: coverage[toml]~=7.6.0; extra == "test"
+Requires-Dist: pytest~=8.3.1; extra == "test"
+Requires-Dist: pytest-cases~=3.8.3; extra == "test"
+Requires-Dist: pytest-cov~=6.0.0; extra == "test"
+Requires-Dist: pytest-github-actions-annotate-failures~=0.2.0; extra == "test"
+Requires-Dist: pytest-randomly~=3.16.0; extra == "test"
+
+# `gha-utils` CLI + reusable workflows
+
+[![Last release](https://img.shields.io/pypi/v/gha-utils.svg)](https://pypi.python.org/pypi/gha-utils)
+[![Python versions](https://img.shields.io/pypi/pyversions/gha-utils.svg)](https://pypi.python.org/pypi/gha-utils)
+[![Type checked with mypy](http://www.mypy-lang.org/static/mypy_badge.svg)](http://mypy-lang.org/)
+[![Unittests status](https://github.com/kdeldycke/workflows/actions/workflows/tests.yaml/badge.svg?branch=main)](https://github.com/kdeldycke/workflows/actions/workflows/tests.yaml?query=branch%3Amain)
+[![Coverage status](https://codecov.io/gh/kdeldycke/workflows/branch/main/graph/badge.svg)](https://app.codecov.io/gh/kdeldycke/workflows)
+
+Thanks to this project, I am able to **release Python packages multiple times a day with only 2-clicks**.
+
+This repository contains a collection of reusable workflows and its companion CLI called `gha-utils` (which stands for *GitHub action workflows utilities*).
+
+It is designed for `uv`-based Python projects (and Awesome List projects as a bonus).
+
+It takes care of:
+
+- Version bumping
+- Formatting autofix for: Python, Markdown, JSON, typos
+- Linting: Python types with `mypy`, YAML, `zsh`, GitHub actions, links, Awesome lists, secrets
+- Compiling of Python binaries for Linux / macOS / Windows on `x86_64` & `arm64`
+- Building of Python packages and upload to PyPi
+- Git version tagging and GitHub release creation
+- Synchronization of: `uv.lock`, `.gitignore`, `.mailmap` and Mermaid dependency graph
+- Auto-locking of inactive closed issues
+- Static image optimization
+- Sphinx documentation building & deployment, and `autodoc` updates
+- Label management, with file-based and content-based rules
+
+Nothing is done behind your back. A PR is created every time a change is proposed, so you can inspect it, ala dependabot.
+
+## `gha-utils` CLI
+
+### Ad-hoc execution
+
+Thanks to `uv`, you can install and run `gha-utils` in one command, without polluting your system:
+
+```shell-session
+$ uvx gha-utils
+Installed 45 packages in 45ms
+Usage: gha-utils [OPTIONS] COMMAND [ARGS]...
+
+Options:
+  --time / --no-time        Measure and print elapsed execution time.  [default:
+                            no-time]
+  --color, --ansi / --no-color, --no-ansi
+                            Strip out all colors and all ANSI codes from output.
+                            [default: color]
+  -C, --config CONFIG_PATH  Location of the configuration file. Supports glob
+                            pattern of local path and remote URL.  [default:
+                            ~/Library/Application Support/gha-
+                            utils/*.{toml,yaml,yml,json,ini,xml}]
+  --show-params             Show all CLI parameters, their provenance, defaults
+                            and value, then exit.
+  -v, --verbosity LEVEL     Either CRITICAL, ERROR, WARNING, INFO, DEBUG.
+                            [default: WARNING]
+  --version                 Show the version and exit.
+  -h, --help                Show this message and exit.
+
+Commands:
+  changelog     Maintain a Markdown-formatted changelog
+  mailmap-sync  Update Git's .mailmap file with missing contributors
+  metadata      Output project metadata
+```
+
+```shell-session
+$ uvx gha-utils --version
+gha-utils, version 4.9.0
+```
+
+That's the best way to get started with `gha-utils`, and experiment with its features.
+
+### Executables
+
+To ease deployment, standalone executables of `gha-utils`'s latest version are available as direct downloads for several platforms and architectures:
+
+| Platform    | `x86_64`                                                                                                                          | `arm64`                                                                                                                           |
+| ----------- | --------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
+| **Linux**   | [Download `gha-utils-linux-x64.bin`](https://github.com/kdeldycke/workflows/releases/latest/download/gha-utils-linux-x64.bin)     |                                                                                                                                   |
+| **macOS**   | [Download `gha-utils-macos-x64.bin`](https://github.com/kdeldycke/workflows/releases/latest/download/gha-utils-macos-x64.bin)     | [Download `gha-utils-macos-arm64.bin`](https://github.com/kdeldycke/workflows/releases/latest/download/gha-utils-macos-arm64.bin) |
+| **Windows** | [Download `gha-utils-windows-x64.exe`](https://github.com/kdeldycke/workflows/releases/latest/download/gha-utils-windows-x64.exe) |                                                                                                                                   |
+
+### Development version
+
+To play with the latest development version of `gha-utils`, you can install it directly from the repository:
+
+```shell-session
+$ git clone https://github.com/kdeldycke/workflows
+$ cd workflows
+$ python -m pip install uv
+$ uv venv
+$ source .venv/bin/activate
+$ uv sync
+$ uv run -- gha-utils
+```
+
+## Reusable workflows collection
+
+This repository contains workflows to automate most of the boring tasks.
+
+These workflows are mostly used for Python projects and their documentation, but not only. They're all [reusable GitHub actions workflows](https://docs.github.com/en/actions/learn-github-actions/reusing-workflows).
+
+Reasons for a centralized workflow repository:
+
+- reusability of course: no need to update dozens of repository where 95% of workflows are the same
+- centralize all dependencies pertaining to automation: think of the point-release of an action that triggers dependabot upgrade to all your repositories depending on it
+
+### Guidelines
+
+I don't want to copy-n-past, keep in sync and maintain another `N`th CI/CD file at the root of my repositories.
+
+So my policy is: move every repository-specific config in a `pyproject.toml` file, or hide the gory details in a reused workflow.
+
+### `.github/workflows/docs.yaml` jobs
+
+- Autofix typos
+
+- Optimize images
+
+- Keep `.mailmap` up to date
+
+- Update dependency graph of Python projects
+
+  - **Requires**:
+    - Python package with a `pyproject.toml` file
+
+- Build Sphinx-based documentation and publish it to GitHub Pages
+
+  - **Requires**:
+    - Python package with a `pyproject.toml` file
+    - All Sphinx dependencies in a `docs` [extra dependency group](https://packaging.python.org/en/latest/guides/writing-pyproject-toml/#dependencies-and-requirements):
+      ```toml
+      [project.optional-dependencies]
+      docs = [
+          "furo == 2024.1.29",
+          "myst-parser ~= 3.0.0",
+          "sphinx >= 6",
+          ...
+      ]
+      ```
+    - Sphinx configuration file at `docs/conf.py`
+
+- Sync awesome projects from `awesome-template` repository
+
+### Why all these `requirements/*.txt` files?
+
+Let's look for example at the `lint-yaml` job from [`.github/workflows/lint.yaml`](https://github.com/kdeldycke/workflows/blob/main/.github/workflows/lint.yaml#L126). Here we only need the `yamllint` CLI. This CLI is [distributed on PyPi](https://pypi.org/project/yamllint/). So before executing it, we could have simply run the following step:
+
+```yaml
+  - name: Install yamllint
+    run: |
+      pip install yamllint
+```
+
+Instead, we install it via the [`requirements/yamllint.txt` file](https://github.com/kdeldycke/workflows/blob/main/requirements/yamllint.txt).
+
+Why? Because I want the version of `yamllint` to be pinned. By pinning it, I make the workflow stable, predictable and reproducible.
+
+So why use a dedicated requirements file? Why don't we simply add the version? Like this:
+
+```yaml
+  - name: Install yamllint
+    run: |
+      pip install yamllint==1.35.1
+```
+
+That would indeed pin the version. But it requires the maintainer (me) to keep track of new release and update manually the version string. That's a lot of work. And I'm lazy. So this should be automated.
+
+To automate that, the only practical way I found was to rely on dependabot. But dependabot cannot update arbitrary versions in `run:` YAML blocks. It [only supports `requirements.txt` and `pyproject.toml`](https://docs.github.com/en/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file#pip-and-pip-compile) files for Python projects.
+
+So to keep track of new versions of dependencies while keeping them stable, we've hard-coded all Python libraries and CLIs in the `requirements/*.txt` files. All with pinned versions.
+
+And for the case we need to install all dependencies in one go, we have a [`requirements.txt` file at the root](https://github.com/kdeldycke/workflows/blob/main/requirements.txt) that is referencing all files from the `requirements/` subfolder.
+
+### Permissions and token
+
+This repository updates itself via GitHub actions. It particularly updates its own YAML files in `.github/workflows`. That's forbidden by default. So we need extra permissions.
+
+Usually, to grant special permissions to some jobs, you use the [`permissions` parameter in workflow](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#permissions) files. It looks like this:
+
+```yaml
+on: (...)
+
+jobs:
+
+  my-job:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      pull-requests: write
+
+    steps: (...)
+```
+
+But the `contents: write` permission doesn't allow write access to the workflow files in the `.github` subfolder. There is `actions: write`, but it only covers workflow runs, not their YAML source file. Even a `permissions: write-all` doesn't work. So you cannot use the `permissions` parameter to allow a repository's workflow update its own workflow files.
+
+You will always end up with this kind or errors:
+
+```text
+   ! [remote rejected] branch_xxx -> branch_xxx (refusing to allow a GitHub App to create or update workflow `.github/workflows/my_workflow.yaml` without `workflows` permission)
+
+  error: failed to push some refs to 'https://github.com/kdeldycke/my-repo'
+```
+
+> [!NOTE]
+> That's also why the Settings > Actions > General > Workflow permissions parameter on your repository has no effect on this issue, even with the `Read and write permissions` set:
+> ![](docs/assets/repo-workflow-permissions.png)
+
+To bypass the limitation, we rely on a custom access token. By convention, we call it `WORKFLOW_UPDATE_GITHUB_PAT`. It will be used, [in place of the default `secrets.GITHUB_TOKEN`](https://github.com/search?q=repo%3Akdeldycke%2Fworkflows%20WORKFLOW_UPDATE_GITHUB_PAT&type=code), in steps in which we need to change the workflow YAML files.
+
+To create this custom `WORKFLOW_UPDATE_GITHUB_PAT`:
+
+- From your GitHub user, go to `Settings` > `Developer Settings` > `Personal Access Tokens` > `Fine-grained tokens`
+- Click on the `Generate new token` button
+- Choose a good token name like `workflow-self-update` to make your intention clear
+- Choose `Only select repositories` and the list the repositories in needs of updating their workflow YAML files
+- In the `Repository permissions` drop-down, sets:
+  - `Contents`: `Access: **Read and Write**`
+  - `Metadata` (mandatory): `Access: **Read-only**`
+  - `Pull Requests`: `Access: **Read and Write**`
+  - `Workflows`: `Access: **Read and Write**`
+    > [!NOTE]
+    > This is the only place where I can have control over the `Workflows` permission, which is not supported by the `permissions:` parameter in YAML files.
+- Now save these parameters and copy the `github_pat_XXXX` secret token
+- Got to your repo > `Settings` > `Security` > `Secrets and variables` > `Actions` > `Secrets` > `Repository secrets` and click `New repository secrets`
+- Name your secret `WORKFLOW_UPDATE_GITHUB_PAT` and copy the `github_pat_XXXX` token in the `Secret` field
+
+Now re-run your actions and they should be able to update the workflow files in `.github` folder without the `refusing to allow a GitHub App to create or update workflow` error.
+
+### Release management
+
+It turns out [Release Engineering is a full-time job, and full of edge-cases](https://blog.axo.dev/2023/02/cargo-dist).
+
+Rust has [`cargo-dist`](https://github.com/axodotdev/cargo-dist). Go has... ? But there is no equivalent for Python.
+
+So I made up a [`release.yaml` workflow](https://github.com/kdeldycke/workflows/blob/main/.github/workflows/release.yaml), which:
+
+1. Extracts project metadata from `pyproject.toml`
+1. Generates a build matrix of all commits / os / arch / CLI entry points
+1. Build Python wheel with Twine
+1. Compile binaries of all CLI with Nuitka
+1. Tag the release commit in Git
+1. Publish new version to PyPi
+1. Publish a GitHub release
+1. Attach and rename build artifacts to it
+
+## Changelog
+
+A [detailed changelog](changelog.md) is available.
+
+## Used in
+
+Check these projects to get real-life examples of usage and inspiration:
+
+- ![GitHub stars](https://img.shields.io/github/stars/kdeldycke/awesome-falsehood?label=%E2%AD%90&style=flat-square) [Awesome Falsehood](https://github.com/kdeldycke/awesome-falsehood#readme) - Falsehoods Programmers Believe in.
+- ![GitHub stars](https://img.shields.io/github/stars/kdeldycke/awesome-engineering-team-management?label=%E2%AD%90&style=flat-square) [Awesome Engineering Team Management](https://github.com/kdeldycke/awesome-engineering-team-management#readme) - How to transition from software development to engineering management.
+- ![GitHub stars](https://img.shields.io/github/stars/kdeldycke/awesome-iam?label=%E2%AD%90&style=flat-square) [Awesome IAM](https://github.com/kdeldycke/awesome-iam#readme) - Identity and Access Management knowledge for cloud platforms.
+- ![GitHub stars](https://img.shields.io/github/stars/kdeldycke/awesome-billing?label=%E2%AD%90&style=flat-square) [Awesome Billing](https://github.com/kdeldycke/awesome-billing#readme) - Billing & Payments knowledge for cloud platforms.
+- ![GitHub stars](https://img.shields.io/github/stars/kdeldycke/meta-package-manager?label=%E2%AD%90&style=flat-square) [Meta Package Manager](https://github.com/kdeldycke/meta-package-manager#readme) - A unifying CLI for multiple package managers.
+- ![GitHub stars](https://img.shields.io/github/stars/kdeldycke/mail-deduplicate?label=%E2%AD%90&style=flat-square) [Mail Deduplicate](https://github.com/kdeldycke/mail-deduplicate#readme) - A CLI to deduplicate similar emails.
+- ![GitHub stars](https://img.shields.io/github/stars/kdeldycke/dotfiles?label=%E2%AD%90&style=flat-square) [dotfiles](https://github.com/kdeldycke/dotfiles#readme) - macOS dotfiles for Python developers.
+- ![GitHub stars](https://img.shields.io/github/stars/kdeldycke/click-extra?label=%E2%AD%90&style=flat-square) [Click Extra](https://github.com/kdeldycke/click-extra#readme) - Extra colorization and configuration loading for Click.
+- ![GitHub stars](https://img.shields.io/github/stars/themagicalmammal/wikibot?label=%E2%AD%90&style=flat-square) [Wiki bot](https://github.com/themagicalmammal/wikibot#readme) - A bot which provides features from Wikipedia like summary, title searches, location API etc.
+- ![GitHub stars](https://img.shields.io/github/stars/kdeldycke/workflows?label=%E2%AD%90&style=flat-square) [workflows](https://github.com/kdeldycke/workflows#readme) - Itself. Eat your own dog-food.
+- ![GitHub stars](https://img.shields.io/github/stars/themagicalmammal/stock-analyser?label=%E2%AD%90&style=flat-square) [Stock Analysis](https://github.com/themagicalmammal/stock-analyser#readme) - Simple to use interfaces for basic technical analysis of stocks.
+- ![GitHub stars](https://img.shields.io/github/stars/themagicalmammal/genetictabler?label=%E2%AD%90&style=flat-square) [GeneticTabler](https://github.com/themagicalmammal/genetictabler#readme) - Time Table Scheduler using Genetic Algorithms.
+- ![GitHub stars](https://img.shields.io/github/stars/themagicalmammal/excel-write?label=%E2%AD%90&style=flat-square) [Excel Write](https://github.com/themagicalmammal/excel-write#readme) - Optimised way to write in excel files.
+
+Feel free to send a PR to add your project in this list if you are relying on these scripts.
+
+## Release process
+
+All steps of the release process and version management are automated in the
+[`changelog.yaml`](https://github.com/kdeldycke/workflows/blob/main/.github/workflows/changelog.yaml)
+and
+[`release.yaml`](https://github.com/kdeldycke/workflows/blob/main/.github/workflows/release.yaml)
+workflows.
+
+All there's left to do is to:
+
+- [check the open draft `prepare-release` PR](https://github.com/kdeldycke/workflows/pulls?q=is%3Apr+is%3Aopen+head%3Aprepare-release)
+  and its changes,
+- click the `Ready for review` button,
+- click the `Rebase and merge` button,
+- let the workflows tag the release and set back the `main` branch into a
+  development state.

gha_utils-4.11.0/gha_utils/__init__.py

@@ -0,0 +1,20 @@
+# Copyright Kevin Deldycke <kevin@deldycke.com> and contributors.
+#
+# This program is Free Software; you can redistribute it and/or
+# modify it under the terms of the GNU General Public License
+# as published by the Free Software Foundation; either version 2
+# of the License, or (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program; if not, write to the Free Software
+# Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
+"""Expose package-wide elements."""
+
+from __future__ import annotations
+
+__version__ = "4.11.0"

gha_utils-4.11.0/gha_utils/__main__.py

@@ -0,0 +1,49 @@
+# Copyright Kevin Deldycke <kevin@deldycke.com> and contributors.
+#
+# This program is Free Software; you can redistribute it and/or
+# modify it under the terms of the GNU General Public License
+# as published by the Free Software Foundation; either version 2
+# of the License, or (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program; if not, write to the Free Software
+# Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
+"""Allow the module to be run as a CLI. I.e.:
+
+.. code-block:: shell-session
+
+    $ python -m gha_utils
+"""
+
+from __future__ import annotations
+
+
+def main():
+    """Execute the CLI but force its name to not let Click defaults to:
+
+    .. code-block:: shell-session
+        $ python -m gha_utils --version
+        python -m gha_utils, version 4.0.0
+
+    Indirection via this ``main()`` method was `required to reconcile
+    <https://github.com/python-poetry/poetry/issues/5981>`_:
+
+        - plain inline package call: ``python -m gha_utils``,
+        - Poetry's script entry point: ``gha-utils = 'gha_utils.__main__:main``,
+        - Nuitka's main module invocation requirement:
+          ``python -m nuitka (...) gha_utils/__main__.py``
+
+    That way we can deduce all three cases from the entry point.
+    """
+    from gha_utils.cli import gha_utils
+
+    gha_utils(prog_name=gha_utils.name)
+
+
+if __name__ == "__main__":
+    main()

gha_utils-4.11.0/gha_utils/changelog.py

@@ -0,0 +1,150 @@
+# Copyright Kevin Deldycke <kevin@deldycke.com> and contributors.
+#
+# This program is Free Software; you can redistribute it and/or
+# modify it under the terms of the GNU General Public License
+# as published by the Free Software Foundation; either version 2
+# of the License, or (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program; if not, write to the Free Software
+# Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
+
+from __future__ import annotations
+
+import logging
+import re
+import sys
+from functools import cached_property
+from pathlib import Path
+from textwrap import indent
+
+if sys.version_info >= (3, 11):
+    import tomllib
+else:
+    import tomli as tomllib  # type: ignore[import-not-found]
+
+
+class Changelog:
+    """Helpers to manipulate changelog files written in Markdown."""
+
+    def __init__(self, initial_changelog: str | None = None) -> None:
+        if not initial_changelog:
+            self.content = "# Changelog\n"
+        else:
+            self.content = initial_changelog
+        logging.debug(f"Initial content set to:\n{self.content}")
+
+    @cached_property
+    def current_version(self) -> str | None:
+        # Extract current version as defined by bump-my-version.
+        config_file = Path("./pyproject.toml").resolve()
+        logging.info(f"Open {config_file}")
+        config = tomllib.loads(config_file.read_text(encoding="UTF-8"))
+        current_version = config["tool"]["bumpversion"]["current_version"]
+        logging.info(f"Current version: {current_version}")
+        return current_version if current_version else None
+
+    def update(self) -> str:
+        r"""Adds a new empty entry at the top of the changelog.
+
+        Will return the same content as the current changelog if it has already been updated.
+
+        This is designed to be used just after a new release has been tagged. And before a
+        post-release version increment is applied with a call to:
+
+        ```shell-session
+        $ bump-my-version bump --verbose patch
+        Starting BumpVersion 0.5.1.dev6
+        Reading config file pyproject.toml:
+        Specified version (2.17.5) does not match last tagged version (2.17.4)
+        Parsing version '2.17.5' using '(?P<major>\\d+)\\.(?P<minor>\\d+)\\.(?P<patch>\\d+)'
+        Parsed the following values: major=2, minor=17, patch=5
+        Attempting to increment part 'patch'
+        Values are now: major=2, minor=17, patch=6
+        New version will be '2.17.6'
+        Dry run active, won't touch any files.
+        Asserting files ./changelog.md contain the version string...
+        Found '[2.17.5 (unreleased)](' in ./changelog.md at line 2:
+        ## [2.17.5 (unreleased)](https://github.com/kdeldycke/workflows/compare/v2.17.4...main)
+        Would change file ./changelog.md:
+        *** before ./changelog.md
+        --- after ./changelog.md
+        ***************
+        *** 1,6 ****
+          # Changelog
+
+        ! ## [2.17.5 (unreleased)](https://github.com/kdeldycke/workflows/compare/v2.17.4...main)
+
+          > [!IMPORTANT]
+          > This version is not released yet and is under active development.
+        --- 1,6 ----
+          # Changelog
+
+        ! ## [2.17.6 (unreleased)](https://github.com/kdeldycke/workflows/compare/v2.17.4...main)
+
+          > [!IMPORTANT]
+          > This version is not released yet and is under active development.
+        Would write to config file pyproject.toml:
+        *** before pyproject.toml
+        --- after pyproject.toml
+        ***************
+        *** 1,5 ****
+          [tool.bumpversion]
+        ! current_version = "2.17.5"
+          allow_dirty = true
+
+          [[tool.bumpversion.files]]
+        --- 1,5 ----
+          [tool.bumpversion]
+        ! current_version = "2.17.6"
+          allow_dirty = true
+
+          [[tool.bumpversion.files]]
+        Would not commit
+        Would not tag since we are not committing
+        ```
+        """
+        # Extract parts of the changelog or set default values.
+        SECTION_START = "##"
+        sections = self.content.split(SECTION_START, 2)
+        changelog_header = sections[0] if len(sections) > 0 else "# Changelog\n\n"
+        current_entry = f"{SECTION_START}{sections[1]}" if len(sections) > 1 else ""
+        past_entries = f"{SECTION_START}{sections[2]}" if len(sections) > 2 else ""
+
+        # Derive the release template from the last entry.
+        DATE_REGEX = r"\d{4}\-\d{2}\-\d{2}"
+        VERSION_REGEX = r"\d+\.\d+\.\d+"
+
+        # Replace the release date with the unreleased tag.
+        new_entry = re.sub(DATE_REGEX, "unreleased", current_entry, count=1)
+
+        # Update GitHub's comparison URL to target the main branch.
+        new_entry = re.sub(
+            rf"v{VERSION_REGEX}\.\.\.v{VERSION_REGEX}",
+            f"v{self.current_version}...main",
+            new_entry,
+            count=1,
+        )
+
+        # Replace the whole paragraph of changes by a notice message. The paragraph is
+        # identified as starting by a blank line, at which point everything gets
+        # replaced.
+        new_entry = re.sub(
+            r"\n\n.*",
+            "\n\n"
+            "> [!IMPORTANT]\n"
+            "> This version is not released yet and is under active development.\n\n",
+            new_entry,
+            flags=re.MULTILINE | re.DOTALL,
+        )
+        logging.info("New generated section:\n" + indent(new_entry, " " * 2))
+
+        history = current_entry + past_entries
+        if new_entry not in history:
+            history = new_entry + history
+        return (changelog_header + history).rstrip()