semversioner 3.0.0__py3-none-any.whl

semversioner/__init__.py

@@ -0,0 +1,14 @@
+from semversioner.__version__ import __version__
+from semversioner.core import Semversioner
+from semversioner.models import (
+    Changeset,
+    MissingChangesetError,
+    Release,
+    ReleaseStatus,
+    ReleaseType,
+    SemversionerError,
+)
+from semversioner.storage import (
+    SemversionerFileSystemStorage,
+    SemversionerStorage,
+)

semversioner/__main__.py

@@ -0,0 +1,9 @@
+from .cli import cli
+
+
+def main() -> None:
+    cli()
+
+
+if __name__ == "__main__":
+    main()

semversioner/__version__.py

@@ -0,0 +1 @@
+__version__ = "3.0.0"

semversioner/cli.py

@@ -0,0 +1,169 @@
+#!/usr/bin/env python
+"""
+Semversioner allows you to manage semantic versioning properly and simplifies changelog generation.
+
+This project was inspired by the way AWS manages their versioning for AWS-CLI: https://github.com/aws/aws-cli/
+
+At any given time, the ``.semversioner/`` directory looks like:
+    .semversioner
+    |
+    └── next-release
+        ├── minor-20181227010225.json
+        └── major-20181228010225.json
+    ├── 1.1.0.json
+    ├── 1.1.1.json
+    ├── 1.1.2.json
+
+This script takes everything in ``next-release`` and aggregates them all together in a single JSON file for that release (e.g ``1.12.0.json``).  This
+JSON file is a list of all the individual JSON files from ``next-release``.
+
+This is done to simplify changelog generation.
+
+Usage
+=====
+::
+    $ semversioner add-change --type major --description "This description will appear in the change log"
+    $ semversioner release
+    $ semversioner changelog > CHANGELOG.md
+    $ semversioner next-version
+"""
+
+import logging
+import sys
+from pathlib import Path
+from typing import TextIO
+
+import click
+
+from semversioner import __version__
+from semversioner.core import Semversioner
+from semversioner.models import MissingChangesetError, Release, ReleaseStatus
+
+
+# Configure the logger for semversioner
+class ClickHandler(logging.Handler):
+    def emit(self, record: logging.LogRecord) -> None:
+        click.echo(self.format(record))
+
+
+logger = logging.getLogger("semversioner")
+logger.setLevel(logging.INFO)
+handler = ClickHandler()
+handler.setFormatter(logging.Formatter("%(message)s"))
+logger.addHandler(handler)
+logger.propagate = False
+
+ROOTDIR = Path.cwd()
+
+
+def parse_key_value_pair(
+    _ctx: click.core.Context | None, _param: click.core.Parameter | None, value: list[str]
+) -> dict[str, str] | None:
+    """
+    Parses a list of strings into a dictionary where each string is a key-value pair.
+    """
+    if not value:
+        return None
+    dict_value = {}
+    for item in value:
+        key, val = item.split("=", 1)
+        dict_value[key] = val
+    return dict_value
+
+
+@click.group()
+@click.option(
+    "--path", default=str(ROOTDIR), help="Base path. Default to current directory.", type=click.Path(exists=True)
+)
+@click.version_option(version=__version__)
+@click.pass_context
+def cli(ctx: click.Context, path: str) -> None:
+    ctx.obj = {"releaser": Semversioner(path=path)}
+
+
+@cli.command("release", help="Release a new version.")
+@click.pass_context
+def cli_release(ctx: click.Context) -> None:
+    releaser: Semversioner = ctx.obj["releaser"]
+    if releaser.is_deprecated():
+        click.secho("WARN", bg="yellow", fg="black", nl=False)
+        click.secho(" deprecated ", fg="magenta", nl=False)
+        click.echo(
+            "Semversioner now uses '.semversioner' directory instead of '.changes'. Please, rename it to remove this message."
+        )
+    try:
+        result: Release = releaser.release()
+        click.echo(message="Successfully created new release: " + result.version)
+    except MissingChangesetError:
+        click.secho("Error: No changes to release. Skipping release process.", fg="red")
+
+
+@cli.command("changelog", help="Print the changelog.")
+@click.option("--version", default=None, help="Filter the changelog by version.")
+@click.option("--template", default=None, help="Path to a custom changelog template.", type=click.File("r"))
+@click.pass_context
+def cli_changelog(ctx: click.Context, version: str | None, template: TextIO | None) -> None:
+    releaser: Semversioner = ctx.obj["releaser"]
+    if template:
+        changelog = releaser.generate_changelog(version=version, template=template.read())
+    else:
+        changelog = releaser.generate_changelog(version=version)
+    click.echo(message=changelog, nl=False)
+
+
+@cli.command("add-change", help="Create a new changeset file.")
+@click.pass_context
+@click.option("--type", "-t", "change_type", type=click.Choice(["major", "minor", "patch"]), required=True)
+@click.option("--description", "-d", required=True)
+@click.option("--attributes", multiple=True, callback=parse_key_value_pair, help="Attributes in key=value format.")
+def cli_add_change(ctx: click.Context, change_type: str, description: str, attributes: dict | None) -> None:
+    releaser: Semversioner = ctx.obj["releaser"]
+    path: str = releaser.add_change(change_type, description, attributes)
+    click.echo(message="Successfully created file " + path)
+
+
+@cli.command("current-version", help="Show the current version.")
+@click.pass_context
+def cli_current_version(ctx: click.Context) -> None:
+    releaser: Semversioner = ctx.obj["releaser"]
+    version = releaser.get_last_version()
+    click.echo(message=version)
+
+
+@cli.command("next-version", help="Show computed next version.")
+@click.pass_context
+def cli_next_version(ctx: click.Context) -> None:
+    releaser: Semversioner = ctx.obj["releaser"]
+    version = releaser.get_next_version()
+    if version is None:
+        click.secho(message="Error: No changes found. No next version available.", fg="red")
+        sys.exit(-1)
+
+    click.echo(message=version, nl=False)
+
+
+@cli.command("status", help="Show the status of the working directory.")
+@click.pass_context
+def status(ctx: click.Context) -> None:
+    releaser: Semversioner = ctx.obj["releaser"]
+    status_info: ReleaseStatus = releaser.get_status()
+    click.echo(message=f"Version: {status_info.version}")
+    if len(status_info.unreleased_changes) > 0:
+        click.echo(message=f"Next version: {status_info.next_version}")
+        click.echo(message="Unreleased changes:")
+        for change in status_info.unreleased_changes:
+            click.secho(message=f"\t{change.type}:\t{change.description}", fg="red")
+        click.echo(message='(use "semversioner release" to release the next version)')
+    else:
+        click.echo(message='No changes to release (use "semversioner add-change")')
+
+
+@cli.command("check", help="Verifies changeset files exist.")
+@click.pass_context
+def cli_check(ctx: click.Context) -> None:
+    releaser: Semversioner = ctx.obj["releaser"]
+    if not releaser.check():
+        click.secho("Error: No changes to release.", fg="red")
+        sys.exit(-1)
+    else:
+        click.echo("OK")

semversioner/core.py

@@ -0,0 +1,180 @@
+import logging
+from datetime import datetime, timezone
+from pathlib import Path
+
+from jinja2 import Template
+
+from semversioner.models import (
+    Changeset,
+    MissingChangesetError,
+    Release,
+    ReleaseStatus,
+    ReleaseType,
+    SemversionerError,
+)
+from semversioner.storage import SemversionerFileSystemStorage
+
+logger = logging.getLogger("semversioner")
+
+ROOTDIR = Path.cwd()
+INITIAL_VERSION = "0.0.0"
+# To add support for dates you can use: {{ ' (' + release.created_at.strftime("%m-%d-%Y") + ')' if release.created_at }}
+DEFAULT_TEMPLATE = """# Changelog
+Note: version releases in the 0.x.y range may introduce breaking changes.
+{% for release in releases %}
+
+## {{ release.version }}
+
+{% for change in release.changes %}
+- {{ change.type }}: {{ change.description }}
+{% endfor %}
+{% endfor %}
+"""
+
+
+class Semversioner:
+    def __init__(self, path: str | Path = ROOTDIR):
+        self.fs = SemversionerFileSystemStorage(path=str(path))
+
+    def is_deprecated(self) -> bool:
+        return self.fs.is_deprecated()
+
+    def add_change(self, change_type: str, description: str, attributes: dict[str, str] | None = None) -> str:
+        """
+        Create a new changeset file.
+
+        The method creates a new json file in the ``.semversioner/next-release/`` directory
+        with the type and description provided.
+
+        Parameters
+        -------
+        change_type (str): Change type. Allowed values: major, minor, patch.
+        description (str): Change description.
+        attributes (dict): Change attributes (Optional).
+
+        Returns
+        -------
+        path : str
+            Absolute path of the file generated.
+        """
+
+        return self.fs.create_changeset(Changeset(type=change_type, description=description, attributes=attributes))
+
+    def generate_changelog(self, version: str | None = None, template: str = DEFAULT_TEMPLATE) -> str:
+        """
+        Generates the changelog.
+
+        The method generates the changelog based on the template file defined
+        in ``DEFAULT_TEMPLATE``.
+
+        Returns
+        -------
+        str
+            Changelog string.
+        """
+        releases: list[Release] = self.fs.list_versions()
+
+        if version is not None:
+            releases = [x for x in releases if x.version == version]
+
+        current_version = self.get_last_version()
+        return Template(template, trim_blocks=True).render(
+            releases=releases,
+            current_version=current_version,
+        )
+
+    def release(self) -> Release:
+        """
+        Performs the release.
+
+        The method performs the release by taking everything in ``next-release`` folder
+        and aggregating all together in a single JSON file for that release (e.g ``1.12.0.json``).
+        The JSON file generated is a list of all the individual JSON files from ``next-release``.
+        After aggregating the files, it removes the ``next-release`` directory.
+
+        Returns
+        -------
+        previous_version : str
+            Previous version.
+        new_version : str
+            New version.
+
+        Raises
+        -------
+        MissingChangesetError: SemversionerError
+        """
+
+        if not self.check():
+            raise MissingChangesetError()
+
+        current_version_number = self.get_last_version()
+        next_version_number = self.get_next_version()
+        changes: list[Changeset] = self.fs.list_changesets()
+
+        if next_version_number is None:
+            raise SemversionerError("Can't calculate next version number.")
+
+        logger.info(f"Releasing version: {current_version_number} -> {next_version_number}")
+
+        release = Release(version=next_version_number, changes=changes, created_at=datetime.now(timezone.utc))
+
+        self.fs.create_version(release)
+        self.fs.remove_all_changesets()
+
+        return release
+
+    def get_last_version(self) -> str:
+        """
+        Gets the current version. Returns '0.0.0' if there are not versions created.
+
+        """
+        return self.fs.get_last_version() or INITIAL_VERSION
+
+    def get_next_version(self) -> str | None:
+        """
+        Gets the next version. Returns None is there are not changeset files created.
+        """
+        changes = self.fs.list_changesets()
+        current_version_number = self.get_last_version()
+
+        if len(changes) == 0:
+            return None
+
+        release_type: str = sorted(x.type for x in changes)[0]
+        next_version: str = self._get_next_version_from_type(current_version_number, release_type)
+        return next_version
+
+    def get_status(self) -> ReleaseStatus:
+        """
+        Displays the status of the working directory.
+        """
+        version = self.get_last_version()
+        changes = self.fs.list_changesets()
+        next_version = self.get_next_version()
+
+        return ReleaseStatus(version=version, next_version=next_version, unreleased_changes=changes)
+
+    def check(self) -> bool:
+        """
+        Check if changeset files are present.
+        This is useful to enforce that changeset files are present before merging PRs to the target branch.
+        """
+        changes: list[Changeset] = self.fs.list_changesets()
+        return len(changes) > 0
+
+    def _get_next_version_from_type(self, current_version: str, release_type: str) -> str:
+        """
+        Returns a string like '1.0.0'.
+        """
+        # Convert to a list of ints: [1, 0, 0].
+        version_parts = [int(i) for i in current_version.split(".")]
+        if release_type == ReleaseType.PATCH.value:
+            version_parts[2] += 1
+        elif release_type == ReleaseType.MINOR.value:
+            version_parts[1] += 1
+            version_parts[2] = 0
+        elif release_type == ReleaseType.MAJOR.value:
+            version_parts[0] += 1
+            version_parts[1] = 0
+            version_parts[2] = 0
+        return ".".join(str(i) for i in version_parts)

semversioner/models.py

@@ -0,0 +1,62 @@
+from dataclasses import dataclass
+from datetime import datetime
+from enum import Enum
+
+
+class SemversionerError(Exception):
+    """
+    Base Exception
+    """
+
+    pass
+
+
+class MissingChangesetError(SemversionerError):
+    """
+    Missing changeset files
+    """
+
+    pass
+
+
+class ReleaseType(Enum):
+    """
+    Represents the type of release.
+    """
+
+    MAJOR = "major"
+    MINOR = "minor"
+    PATCH = "patch"
+
+
+@dataclass(frozen=True)
+class Changeset:
+    """
+    Represents a change in the version.
+    """
+
+    type: str
+    description: str
+    attributes: dict[str, str] | None = None
+
+
+@dataclass(frozen=True)
+class Release:
+    """
+    Represents a release.
+    """
+
+    version: str
+    changes: list[Changeset]
+    created_at: datetime | None = None
+
+
+@dataclass(frozen=True)
+class ReleaseStatus:
+    """
+    Represents the status of the release in a particular point of time.
+    """
+
+    version: str
+    next_version: str | None
+    unreleased_changes: list[Changeset]

semversioner/storage.py

@@ -0,0 +1,224 @@
+import dataclasses
+import json
+import logging
+from abc import ABCMeta, abstractmethod
+from datetime import datetime, timezone
+from pathlib import Path
+
+from packaging.version import parse
+
+from semversioner.models import Changeset, Release
+
+logger = logging.getLogger("semversioner")
+
+
+class SemversionerStorage(metaclass=ABCMeta):
+    """
+    Abstract base class that defines the interface for a storage class in a semversioner system.
+    The storage class is responsible for creating, listing, and managing changesets and versions.
+    """
+
+    @abstractmethod
+    def is_deprecated(self) -> bool:
+        """
+        Determines if the storage is deprecated.
+        """
+        pass
+
+    @abstractmethod
+    def create_changeset(self, change: Changeset) -> str:
+        """
+        Creates a changeset in the storage.
+        """
+        pass
+
+    @abstractmethod
+    def remove_all_changesets(self) -> None:
+        """
+        Removes all changesets from the storage.
+        """
+        pass
+
+    @abstractmethod
+    def list_changesets(self) -> list[Changeset]:
+        """
+        Retrieves a list of all changesets in the storage.
+        """
+        pass
+
+    @abstractmethod
+    def create_version(self, release: Release) -> None:
+        """
+        Creates a new version in the storage.
+        """
+        pass
+
+    @abstractmethod
+    def list_versions(self) -> list[Release]:
+        """
+        Lists all versions in the storage.
+        """
+        pass
+
+    @abstractmethod
+    def get_last_version(self) -> str | None:
+        """
+        Retrieves the latest version from the storage. Returns None if no versions exist.
+        """
+        pass
+
+
+class EnhancedJSONEncoder(json.JSONEncoder):
+    """
+    This class extends the built-in json.JSONEncoder class to provide a custom encoding for dataclasses.
+    By default, the json.JSONEncoder class doesn't know how to encode dataclasses, so we define a custom encoding here.
+    """
+
+    def default(self, o):
+        if dataclasses.is_dataclass(o):
+            return dataclasses.asdict(o, dict_factory=lambda x: {k: v for (k, v) in x if v is not None})
+        return super().default(o)
+
+
+class ReleaseJsonMapper:
+    """
+    Provides functionality to convert a Release object to JSON and vice versa.
+    """
+
+    @staticmethod
+    def to_json(release: Release) -> str:
+        """
+        Converts a Release object to a JSON-formatted string.
+        """
+        data = {
+            "version": release.version,
+            "created_at": release.created_at.isoformat(timespec="seconds") if release.created_at else None,
+            "changes": release.changes,
+        }
+
+        return json.dumps(data, cls=EnhancedJSONEncoder, indent=2, sort_keys=True)
+
+    @staticmethod
+    def from_json(data: dict, release_identifier: str) -> Release:
+        """
+        Creates a Release object from a JSON-formatted string.
+        """
+        created_at: datetime | None = None
+
+        if "created_at" in data:  # New format
+            created_at = datetime.fromisoformat(data["created_at"])
+            version = data["version"]
+            changes = sorted(data["changes"], key=lambda k: k["type"] + k["description"])
+        else:
+            changes = sorted(data, key=lambda k: k["type"] + k["description"])
+            version = release_identifier
+
+        return Release(version=version, changes=changes, created_at=created_at)
+
+
+class SemversionerFileSystemStorage(SemversionerStorage):
+    def __init__(self, path: str):
+        base_path = Path(path)
+        semversioner_path_legacy = base_path / ".changes"
+        semversioner_path_new = base_path / ".semversioner"
+        semversioner_path = semversioner_path_new
+        deprecated = False
+
+        if semversioner_path_legacy.is_dir() and not semversioner_path_new.is_dir():
+            deprecated = True
+            semversioner_path = semversioner_path_legacy
+        if not semversioner_path.is_dir():
+            semversioner_path.mkdir(parents=True)
+
+        next_release_path = semversioner_path / "next-release"
+        if not next_release_path.is_dir():
+            next_release_path.mkdir(parents=True)
+
+        self.path = base_path
+        self.semversioner_path = semversioner_path
+        self.next_release_path = next_release_path
+        self.deprecated = deprecated
+
+    def is_deprecated(self) -> bool:
+        return self.deprecated
+
+    def create_changeset(self, change: Changeset) -> str:
+        """
+        Create a new changeset file.
+
+        The method creates a new json file in the ``.semversioner/next-release/`` directory
+        with the type and description provided.
+
+        Parameters
+        -------
+        change (Changeset): Changeset.
+
+        Returns
+        -------
+        path : str
+            Absolute path of the file generated.
+        """
+
+        # Retry loop with atomic file creation to prevent race conditions
+        while True:
+            filename = f"{change.type}-{datetime.now(timezone.utc):%Y%m%d%H%M%S%f}.json"
+            full_path = self.next_release_path / filename
+
+            try:
+                # Use 'x' mode for exclusive creation - fails if file already exists
+                with full_path.open("x") as f:
+                    f.write(json.dumps(change, cls=EnhancedJSONEncoder, indent=2) + "\n")
+                return str(full_path)
+            except FileExistsError:
+                # File already exists, retry with a new timestamp
+                continue
+
+    def remove_all_changesets(self) -> None:
+        logger.info(f"Removing changeset files in '{self.next_release_path}' directory.")
+
+        # Remove all json files in next_release_path
+        for file_path in self.next_release_path.iterdir():
+            if file_path.suffix == ".json":
+                file_path.unlink()
+        # Remove next_release_path if the directory is empty
+        if not any(self.next_release_path.iterdir()):
+            logger.info(f"Removing '{self.next_release_path}' directory.")
+            self.next_release_path.rmdir()
+
+    def list_changesets(self) -> list[Changeset]:
+        changes: list[Changeset] = []
+        next_release_dir = self.next_release_path
+        if not next_release_dir.is_dir():
+            return changes
+        for file_path in next_release_dir.iterdir():
+            if file_path.suffix == ".json":
+                with file_path.open() as f:
+                    change_data = json.load(f)
+                    changes.append(Changeset(**change_data))
+        return sorted(changes, key=lambda k: k.type + k.description)
+
+    def create_version(self, release: Release) -> None:
+        version: str = release.version
+        release_json_file = self.semversioner_path / f"{version}.json"
+        with release_json_file.open("w") as f:
+            f.write(ReleaseJsonMapper.to_json(release))
+        logger.info(f"Generated '{release_json_file}' file.")
+
+    def list_versions(self) -> list[Release]:
+        releases: list[Release] = []
+        for release_identifier in self._list_release_numbers():
+            release_json_file = self.semversioner_path / f"{release_identifier}.json"
+            with release_json_file.open() as f:
+                data = json.load(f)
+                releases.append(ReleaseJsonMapper.from_json(data, release_identifier))
+        return releases
+
+    def get_last_version(self) -> str | None:
+        releases = self._list_release_numbers()
+        if len(releases) > 0:
+            return releases[0]
+        return None
+
+    def _list_release_numbers(self) -> list[str]:
+        files = [f.name for f in self.semversioner_path.iterdir() if f.is_file()]
+        return sorted((x[: -len(".json")] for x in files if x.endswith(".json")), key=lambda x: parse(x), reverse=True)

semversioner-3.0.0.dist-info/METADATA

@@ -0,0 +1,252 @@
+Metadata-Version: 2.4
+Name: semversioner
+Version: 3.0.0
+Summary: Manage properly semver in your repository
+Author-email: Raul Gomis <raulgomis@gmail.com>
+License: MIT License
+        
+        Copyright (c) 2020-2026 Raul Gomis
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
+Project-URL: Homepage, https://github.com/raulgomis/semversioner
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python
+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 :: 3.14
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: click>=8.0.0
+Requires-Dist: jinja2>=3.0.0
+Requires-Dist: packaging>=21.0
+Provides-Extra: dev
+Requires-Dist: pytest>=9.0.0; extra == "dev"
+Requires-Dist: pytest-cov>=6.0.0; extra == "dev"
+Requires-Dist: importlib_resources>=6.0.0; extra == "dev"
+Requires-Dist: ruff>=0.9.0; extra == "dev"
+Dynamic: license-file
+
+# Semversioner
+
+The easiest way to manage [semantic versioning](https://semver.org/) in your project and generate `CHANGELOG.md` files automatically.
+
+Semversioner provides the tooling to automate the semver release process for libraries, docker images, microservices, and more.
+
+This project was inspired by the way AWS manages their versioning for [AWS-cli](https://github.com/aws/aws-cli/).
+
+[![PyPI Version](https://img.shields.io/pypi/v/semversioner.svg)](https://pypi.org/project/semversioner/)
+
+## Semantic Versioning
+
+The [semantic versioning](https://semver.org/) spec involves several possible variations, but to simplify, in _Semversioner_ we are using the three-part version number:
+
+`<major>.<minor>.<patch>`
+
+Constructed with the following guidelines:
+
+- Breaking backward compatibility or major features bumps the **major** (and resets the minor and patch).
+- New additions without breaking backward compatibility bumps the **minor** (and resets the patch).
+- Bug fixes and misc changes bumps the **patch**.
+
+An example would be `1.0.0`.
+
+## How it works
+
+At any given time, the `.semversioner/` directory looks like:
+
+```text
+.semversioner
+├── next-release
+│   ├── minor-20181227010225.json
+│   └── major-20181228010225.json
+├── 1.1.0.json
+├── 1.1.1.json
+└── 1.1.2.json
+```
+
+The release process takes everything in the `next-release` directory and aggregates them all together in a single JSON file for that release (e.g., `1.12.0.json`). This JSON file is a list of all the individual JSON files from `next-release`.
+
+## Install
+
+```shell
+pip install semversioner
+```
+
+## Usage
+
+You can use the `--help` option on any command to see the available options:
+
+```shell
+semversioner --help
+```
+
+### Adding changesets
+
+In your local environment, you can use the CLI to create the different changeset files that will be committed with your code. This ensures that every pull request or commit contains its own self-contained change description and version bump intention.
+
+```shell
+semversioner add-change --type patch --description "Fix security vulnerability with authentication."
+```
+
+Allowed `--type` values are: `major`, `minor`, `patch`.
+
+You can also add custom attributes to the changeset file that will be available later in your release template. Use the `--attributes` flag in `key=value` format (you can pass it multiple times):
+
+```shell
+semversioner add-change --type patch \
+    --description "My custom changelog message with attributes." \
+    --attributes pr_id=322 \
+    --attributes issue_id=123
+```
+
+### Checking working directory status
+
+You can check the status of your working directory to see the current version, the computed next version, and any unreleased changes:
+
+```shell
+semversioner status
+```
+
+Example output:
+
+```text
+Version: 1.0.0
+Next version: 1.1.0
+Unreleased changes:
+	minor:	Added new authentication feature
+(use "semversioner release" to release the next version)
+```
+
+### Enforcing changesets in CI/CD (Check)
+
+In your CI/CD pipeline, it's often useful to enforce that a PR includes a changeset before merging. You can use the `check` command to verify that there are unreleased changes in the `.semversioner/next-release/` directory.
+
+```shell
+semversioner check
+```
+
+If no changes are found, the command exits with a non-zero status code (`-1`) and prints an error message.
+
+### Releasing a new version
+
+When you are ready to create a release (usually in your CI/CD tool on the main branch), you run the `release` command. This automatically computes the new version number based on the unreleased changes, generates a new version JSON file, and clears the `next-release` directory.
+
+```shell
+semversioner release
+```
+
+### Generating the Changelog
+
+As part of your release workflow, you can generate the changelog file with all aggregated changes.
+
+```shell
+semversioner changelog > CHANGELOG.md
+```
+
+#### Customizing the changelog template
+
+You can customize the changelog by creating a template and passing it as a parameter to the command. For example:
+
+```shell
+semversioner changelog --template .semversioner/config/template.j2
+```
+
+The template uses [Jinja2](https://jinja.palletsprojects.com/en/3.1.x/), a templating language for Python. A basic example:
+
+```jinja2
+# Changelog
+{% for release in releases %}
+
+## {{ release.version }}
+
+{% for change in release.changes %}
+- {{ change.type }}: {{ change.description }}
+{% endfor %}
+{% endfor %}
+```
+
+If you included custom attributes (e.g., `pr_id`, `issue_id`) using the `add-change` command, you can reference them in your template. You also have access to `current_version`:
+
+```jinja2
+# Changelog
+Note: version releases in the 0.x.y range may introduce breaking changes.
+
+# Current version: {{ current_version }}
+
+{% for release in releases %}
+
+## {{ release.version }}{{ ' (' + release.created_at.strftime('%Y-%m-%d') + ')' if release.created_at }}
+
+{% for change in release.changes %}
+- {{ change.type }}: {{ change.description }}{{ ' (#' + change.attributes.pr_id + ')' if change.attributes }}{{ ' (J' + change.attributes.issue_id + ')' if change.attributes }}
+{% endfor %}
+{% endfor %}
+```
+
+#### Filtering the changelog
+
+You can filter the changelog by only showing changes for a specific version:
+
+```shell
+semversioner changelog --version "1.0.0"
+```
+
+Alternatively, you can filter changes for the last released version:
+
+```shell
+semversioner changelog --version $(semversioner current-version)
+```
+
+### Getting the current version
+
+You can retrieve the currently released version of your project:
+
+```shell
+semversioner current-version
+```
+
+### Getting the next version
+
+As part of the CI/CD workflow, sometimes you want to release dev, rc, or other pre-release packages. For this purpose, the `next-version` command can be issued to compute the upcoming version based on the current changeset. This will not modify any files on disk.
+
+```shell
+semversioner next-version
+```
+
+## Global Options
+
+- `--path`: Specify a custom base path for your project. Defaults to the current directory. Example: `semversioner --path /path/to/project release`
+
+## License
+
+Copyright (c) 2026 Raul Gomis.
+MIT licensed, see [LICENSE](LICENSE) file.
+
+---
+Made with ♥ by [Raul Gomis](https://twitter.com/rgomis).

semversioner-3.0.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+semversioner/__init__.py,sha256=MMhdivi9feYBsQhzsKb8e-LyJ6hmXXTqWMC5Ncblds4,339
+semversioner/__main__.py,sha256=Z9ms2FZUlo8L-vveo4ivpepVJsbjEPBSjDAZF7y11vA,93
+semversioner/__version__.py,sha256=EPmgXOdWKks5S__ZMH7Nu6xpAeVrZpfxaFy4pykuyeI,22
+semversioner/cli.py,sha256=mbxTygEQ2i8EvVUnfu-TUxyIsX_tvPjSUDA1aKEkOco,6224
+semversioner/core.py,sha256=zB9YkgANXFD2vwNLvwwr5VOdBbBCklAhigBuu9rxLNA,5898
+semversioner/models.py,sha256=7esoT9X46Do74SP7UQMejeZ2DtjCJSoAFNoRXtDDTVU,984
+semversioner/storage.py,sha256=tDtbsw0SU84bitHdp9jIs7YGV6eB0GYZGj3fPnnx1IA,7748
+semversioner-3.0.0.dist-info/licenses/LICENSE,sha256=BWexocEqoNJxx_9oeWLgRy7Ybp05IUh1tx-jMdnwzCM,1072
+semversioner-3.0.0.dist-info/METADATA,sha256=-9VcyrTF78clapserjoKQZjZCgyhdXxooSJkNo0kUss,8769
+semversioner-3.0.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+semversioner-3.0.0.dist-info/entry_points.txt,sha256=DiOn5HsCdcEO7eORmsm9pEd9yRTixG1u_Fv5kBOM8dM,60
+semversioner-3.0.0.dist-info/top_level.txt,sha256=cL85ZNjxcHLYEQV02DtdKwtxzy-L-blj3LZ2y5q8fFI,13
+semversioner-3.0.0.dist-info/RECORD,,

semversioner-3.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

semversioner-3.0.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+semversioner = semversioner.__main__:main

semversioner-3.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2020-2026 Raul Gomis
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

semversioner-3.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+semversioner