releez 0.2.2__tar.gz

releez-0.2.2/PKG-INFO

@@ -0,0 +1,225 @@
+Metadata-Version: 2.3
+Name: releez
+Version: 0.2.2
+Summary: CLI tool for helping to manage release processes.
+Requires-Dist: typer==0.20.0
+Requires-Dist: gitpython>=3.1.45,<4
+Requires-Dist: pygithub>=2.8.1,<3
+Requires-Dist: git-cliff>=2.11.0,<3
+Requires-Dist: semver>=3.0.1,<4
+Requires-Dist: pydantic>=2.7.0,<3
+Requires-Dist: pydantic-settings>=2.7.0,<3
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+# `releez`
+
+`releez` is a CLI tool for managing semantic versioned releases.
+
+`releez` uses [`git-cliff`](https://git-cliff.org/) for versioning logic and
+changelog generation under the hood. You should host a `cliff.toml` or other
+compatible `git-cliff` configuration in your repo. Review the `git-cliff`
+documentation for deatils.
+
+## Usage
+
+Start a release from your repo (requires `git` on `PATH`):
+
+`releez release start`
+
+Common options:
+
+- `--bump auto|patch|minor|major`
+- `--base main`
+- `--changelog-path CHANGELOG.md` (or `--changelog`)
+- `--no-create-pr` (skip GitHub PR creation)
+- `--github-token ...` (or set `RELEEZ_GITHUB_TOKEN`, falling back to
+  `GITHUB_TOKEN`)
+- `--dry-run`
+
+Compute an artifact version for CI:
+
+`releez version artifact`
+
+Common options:
+
+- `--scheme docker|semver|pep440`
+- `--version-override ...`
+- `--is-full-release`
+- `--prerelease-type alpha|beta|rc`
+- `--prerelease-number ...`
+- `--build-number ...`
+- `--alias-versions none|major|minor` (full releases only)
+
+Examples:
+
+- Docker PR build:
+  `releez version artifact --scheme docker --version-override 0.1.0 --prerelease-type alpha --prerelease-number 123 --build-number 456`
+  (outputs `0.1.0-alpha123-456`)
+- Python PR build:
+  `releez version artifact --scheme pep440 --version-override 0.1.0 --prerelease-type alpha --prerelease-number 123 --build-number 456`
+- Main branch RC build:
+  `releez version artifact --scheme docker --version-override 0.1.0 --prerelease-type rc --prerelease-number 0 --build-number 456`
+  (outputs `0.1.0-rc0-456`)
+
+Create git tags for a release:
+
+`releez release tag` (tags the git-cliff computed release version; pushes tags
+to `origin` by default)
+
+Override the tagged version if needed:
+
+`releez release tag --version-override 2.3.4`
+
+Optionally update major/minor tags:
+
+- Major only:
+  `releez release tag --version-override 2.3.4 --alias-versions major` (creates
+  `2.3.4` and `v2`)
+- Major + minor:
+  `releez release tag --version-override 2.3.4 --alias-versions minor` (creates
+  `2.3.4`, `v2`, `v2.3`)
+
+Preview what will be published (version and tags):
+
+`releez release preview` (prints markdown to stdout)
+
+`releez release preview --output release-preview.md` (write markdown to a file)
+
+Generate the unreleased changelog section for the release:
+
+`releez release notes` (prints markdown to stdout)
+
+`releez release notes --output release-notes.md` (write markdown to a file)
+
+Regenerate the entire changelog from git history:
+
+`releez changelog regenerate` (regenerates `CHANGELOG.md` using git-cliff)
+
+Common options:
+
+- `--changelog-path CHANGELOG.md` (specify a different changelog file)
+- `--run-changelog-format` (run the configured format hook after regeneration)
+- `--changelog-format-cmd ...` (override the configured format command)
+
+This is useful for fixing changelog formatting issues or rebuilding the
+changelog after repository changes.
+
+## Configuration
+
+`releez` supports configuration via:
+
+1. CLI flags for a command (highest)
+2. `RELEEZ_*` environment variables
+3. `releez.toml` in the repo root
+4. `pyproject.toml` under `[tool.releez]` (lowest)
+
+Config values are applied as defaults for relevant CLI options; passing the CLI
+flag always wins.
+
+### Config keys
+
+TOML config supports both `snake_case` and `kebab-case` keys.
+
+Env vars always use `RELEEZ_` + `SNAKE_CASE`, with `__` for nesting. Example:
+`RELEEZ_HOOKS__CHANGELOG_FORMAT`.
+
+### Supported settings
+
+These are the settings currently loaded from config/env:
+
+- `base_branch` (`--base` on `release start`)
+- `git_remote` (`--remote` on `release start` / `release tag`)
+- `pr_labels` (`--labels` on `release start`)
+- `pr_title_prefix` (`--title-prefix` on `release start`)
+- `changelog_path` (`--changelog-path` on `release start` /
+  `changelog regenerate`)
+- `create_pr` (`--create-pr/--no-create-pr` on `release start`)
+- `run_changelog_format` (`--run-changelog-format` on `release start` /
+  `changelog regenerate`)
+- `hooks.changelog_format` (used by `release start` and `changelog regenerate`
+  when formatting is enabled)
+- `alias_versions` (`--alias-versions` on `release tag` / `release preview` /
+  `version artifact`)
+
+Other flags (e.g. `--version-override`, `--scheme`, `--build-number`) are
+runtime inputs and are not read from config files.
+
+### Examples
+
+`pyproject.toml`:
+
+```toml
+[tool.releez]
+base-branch = "master"
+git-remote = "origin"
+alias-versions = "minor"
+run-changelog-format = true
+
+[tool.releez.hooks]
+changelog-format = ["poe", "format-dprint", "{changelog}"]
+```
+
+`releez.toml`:
+
+```toml
+base_branch = "main"
+git_remote = "origin"
+alias_versions = "minor"
+run_changelog_format = true
+
+[hooks]
+changelog_format = ["poe", "format-dprint", "{changelog}"]
+```
+
+Environment variables:
+
+```bash
+export RELEEZ_GIT_REMOTE=origin
+export RELEEZ_ALIAS_VERSIONS=major
+export RELEEZ_HOOKS__CHANGELOG_FORMAT='["poe","format-dprint","{changelog}"]'
+```
+
+Notes:
+
+- `releez` prefers `RELEEZ_GITHUB_TOKEN` over `GITHUB_TOKEN` for PR creation;
+  the token is read separately and is not part of `RELEEZ_*` settings.
+- `{changelog}` in `changelog_format` is replaced with the configured changelog
+  path before execution.
+
+## GitHub actions
+
+We've built two GitHub reusable actions which use `releez` to streamline
+integration with CI pipelines. Review the documentation for each action for more
+details.
+
+### [`releez-version-artifact-action`](https://github.com/hotdog-werx/releez-version-artifact-action)
+
+This action can be used during CI to generate artifact versions with versions
+corresponding to the versions suggested by `releez` (and implicitly,
+`git-cliff`).
+
+### [`releez-finalize-action`](https://github.com/hotdog-werx/releez-finalize-action)
+
+This action can be run to finalize a release. You can see
+[this workflow](./.github/workflows/finalize-release.yaml) for an example a
+usage.
+
+It applies tags and outputs artifact versions as well as release notes that can
+be used subsequently to create a GitHub Release.
+
+A release should first be started with `releez release start`, usually locally,
+unless you've given your actions permission to create PRs, such as via a GitHub
+App.
+
+## GitHub recommendations
+
+If you use GitHub PRs, prefer squashing and using the PR title as the squash
+commit message:
+
+- Enable “Allow squash merging”
+- Set “Default commit message” to “Pull request title”
+
+This keeps your main branch history aligned with semantic PR titles (and works
+well with `amannn/action-semantic-pull-request` and changelog generation via
+`git-cliff`).

releez-0.2.2/README.md

@@ -0,0 +1,211 @@
+# `releez`
+
+`releez` is a CLI tool for managing semantic versioned releases.
+
+`releez` uses [`git-cliff`](https://git-cliff.org/) for versioning logic and
+changelog generation under the hood. You should host a `cliff.toml` or other
+compatible `git-cliff` configuration in your repo. Review the `git-cliff`
+documentation for deatils.
+
+## Usage
+
+Start a release from your repo (requires `git` on `PATH`):
+
+`releez release start`
+
+Common options:
+
+- `--bump auto|patch|minor|major`
+- `--base main`
+- `--changelog-path CHANGELOG.md` (or `--changelog`)
+- `--no-create-pr` (skip GitHub PR creation)
+- `--github-token ...` (or set `RELEEZ_GITHUB_TOKEN`, falling back to
+  `GITHUB_TOKEN`)
+- `--dry-run`
+
+Compute an artifact version for CI:
+
+`releez version artifact`
+
+Common options:
+
+- `--scheme docker|semver|pep440`
+- `--version-override ...`
+- `--is-full-release`
+- `--prerelease-type alpha|beta|rc`
+- `--prerelease-number ...`
+- `--build-number ...`
+- `--alias-versions none|major|minor` (full releases only)
+
+Examples:
+
+- Docker PR build:
+  `releez version artifact --scheme docker --version-override 0.1.0 --prerelease-type alpha --prerelease-number 123 --build-number 456`
+  (outputs `0.1.0-alpha123-456`)
+- Python PR build:
+  `releez version artifact --scheme pep440 --version-override 0.1.0 --prerelease-type alpha --prerelease-number 123 --build-number 456`
+- Main branch RC build:
+  `releez version artifact --scheme docker --version-override 0.1.0 --prerelease-type rc --prerelease-number 0 --build-number 456`
+  (outputs `0.1.0-rc0-456`)
+
+Create git tags for a release:
+
+`releez release tag` (tags the git-cliff computed release version; pushes tags
+to `origin` by default)
+
+Override the tagged version if needed:
+
+`releez release tag --version-override 2.3.4`
+
+Optionally update major/minor tags:
+
+- Major only:
+  `releez release tag --version-override 2.3.4 --alias-versions major` (creates
+  `2.3.4` and `v2`)
+- Major + minor:
+  `releez release tag --version-override 2.3.4 --alias-versions minor` (creates
+  `2.3.4`, `v2`, `v2.3`)
+
+Preview what will be published (version and tags):
+
+`releez release preview` (prints markdown to stdout)
+
+`releez release preview --output release-preview.md` (write markdown to a file)
+
+Generate the unreleased changelog section for the release:
+
+`releez release notes` (prints markdown to stdout)
+
+`releez release notes --output release-notes.md` (write markdown to a file)
+
+Regenerate the entire changelog from git history:
+
+`releez changelog regenerate` (regenerates `CHANGELOG.md` using git-cliff)
+
+Common options:
+
+- `--changelog-path CHANGELOG.md` (specify a different changelog file)
+- `--run-changelog-format` (run the configured format hook after regeneration)
+- `--changelog-format-cmd ...` (override the configured format command)
+
+This is useful for fixing changelog formatting issues or rebuilding the
+changelog after repository changes.
+
+## Configuration
+
+`releez` supports configuration via:
+
+1. CLI flags for a command (highest)
+2. `RELEEZ_*` environment variables
+3. `releez.toml` in the repo root
+4. `pyproject.toml` under `[tool.releez]` (lowest)
+
+Config values are applied as defaults for relevant CLI options; passing the CLI
+flag always wins.
+
+### Config keys
+
+TOML config supports both `snake_case` and `kebab-case` keys.
+
+Env vars always use `RELEEZ_` + `SNAKE_CASE`, with `__` for nesting. Example:
+`RELEEZ_HOOKS__CHANGELOG_FORMAT`.
+
+### Supported settings
+
+These are the settings currently loaded from config/env:
+
+- `base_branch` (`--base` on `release start`)
+- `git_remote` (`--remote` on `release start` / `release tag`)
+- `pr_labels` (`--labels` on `release start`)
+- `pr_title_prefix` (`--title-prefix` on `release start`)
+- `changelog_path` (`--changelog-path` on `release start` /
+  `changelog regenerate`)
+- `create_pr` (`--create-pr/--no-create-pr` on `release start`)
+- `run_changelog_format` (`--run-changelog-format` on `release start` /
+  `changelog regenerate`)
+- `hooks.changelog_format` (used by `release start` and `changelog regenerate`
+  when formatting is enabled)
+- `alias_versions` (`--alias-versions` on `release tag` / `release preview` /
+  `version artifact`)
+
+Other flags (e.g. `--version-override`, `--scheme`, `--build-number`) are
+runtime inputs and are not read from config files.
+
+### Examples
+
+`pyproject.toml`:
+
+```toml
+[tool.releez]
+base-branch = "master"
+git-remote = "origin"
+alias-versions = "minor"
+run-changelog-format = true
+
+[tool.releez.hooks]
+changelog-format = ["poe", "format-dprint", "{changelog}"]
+```
+
+`releez.toml`:
+
+```toml
+base_branch = "main"
+git_remote = "origin"
+alias_versions = "minor"
+run_changelog_format = true
+
+[hooks]
+changelog_format = ["poe", "format-dprint", "{changelog}"]
+```
+
+Environment variables:
+
+```bash
+export RELEEZ_GIT_REMOTE=origin
+export RELEEZ_ALIAS_VERSIONS=major
+export RELEEZ_HOOKS__CHANGELOG_FORMAT='["poe","format-dprint","{changelog}"]'
+```
+
+Notes:
+
+- `releez` prefers `RELEEZ_GITHUB_TOKEN` over `GITHUB_TOKEN` for PR creation;
+  the token is read separately and is not part of `RELEEZ_*` settings.
+- `{changelog}` in `changelog_format` is replaced with the configured changelog
+  path before execution.
+
+## GitHub actions
+
+We've built two GitHub reusable actions which use `releez` to streamline
+integration with CI pipelines. Review the documentation for each action for more
+details.
+
+### [`releez-version-artifact-action`](https://github.com/hotdog-werx/releez-version-artifact-action)
+
+This action can be used during CI to generate artifact versions with versions
+corresponding to the versions suggested by `releez` (and implicitly,
+`git-cliff`).
+
+### [`releez-finalize-action`](https://github.com/hotdog-werx/releez-finalize-action)
+
+This action can be run to finalize a release. You can see
+[this workflow](./.github/workflows/finalize-release.yaml) for an example a
+usage.
+
+It applies tags and outputs artifact versions as well as release notes that can
+be used subsequently to create a GitHub Release.
+
+A release should first be started with `releez release start`, usually locally,
+unless you've given your actions permission to create PRs, such as via a GitHub
+App.
+
+## GitHub recommendations
+
+If you use GitHub PRs, prefer squashing and using the PR title as the squash
+commit message:
+
+- Enable “Allow squash merging”
+- Set “Default commit message” to “Pull request title”
+
+This keeps your main branch history aligned with semantic PR titles (and works
+well with `amannn/action-semantic-pull-request` and changelog generation via
+`git-cliff`).

releez-0.2.2/pyproject.toml

@@ -0,0 +1,47 @@
+[project]
+name = "releez"
+description = "CLI tool for helping to manage release processes."
+readme = "README.md"
+requires-python = ">=3.11"
+version = "0.2.2"
+
+dependencies = [
+  "typer ==0.20.0",
+  "GitPython >= 3.1.45, <4",
+  "PyGithub >= 2.8.1, <3",
+  "git-cliff >=2.11.0, <3",
+  "semver >=3.0.1, <4",
+  "pydantic >=2.7.0, <3",
+  "pydantic-settings >=2.7.0, <3",
+]
+
+[dependency-groups]
+dev = [
+  "pytest >=9.0.2, <10",
+  "pytest-cov >=7.0.0, <8",
+  "pytest-mock >=3.15.1, <4",
+]
+
+[project.scripts]
+releez = "releez.cli:main"
+
+[tool.ruff]
+extend = ".codeguide/configs/ruff.toml"
+
+[tool.pyright]
+typeCheckingMode = "standard"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.uv.build-backend]
+module-name = "releez"
+module-root = "src"
+
+[tool.releez]
+create-pr = true
+hooks = { changelog-format = ["mise", "exec", "--", "poe", "format-dprint", "{changelog}"] }
+
+[build-system]
+requires = ["uv_build"]
+build-backend = "uv_build"

releez-0.2.2/src/releez/__init__.py

@@ -0,0 +1 @@
+from __future__ import annotations

releez-0.2.2/src/releez/artifact_version.py

@@ -0,0 +1,111 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import StrEnum
+
+from releez.cliff import GitCliff
+from releez.errors import (
+    BuildNumberRequiredError,
+    PrereleaseNumberRequiredError,
+)
+from releez.git_repo import open_repo
+
+
+class ArtifactVersionScheme(StrEnum):
+    """Output scheme for artifact versions."""
+
+    semver = 'semver'
+    docker = 'docker'
+    pep440 = 'pep440'
+
+
+class PrereleaseType(StrEnum):
+    """Supported prerelease types.
+
+    These are deliberately limited so we can reliably map to PEP 440.
+    """
+
+    alpha = 'alpha'
+    beta = 'beta'
+    rc = 'rc'
+
+
+@dataclass(frozen=True)
+class ArtifactVersionInput:
+    """Inputs for computing an artifact version.
+
+    Attributes:
+        scheme: Output scheme for the artifact version.
+        version_override: If set, use this instead of computing via git-cliff.
+        is_full_release: If true, output a full release version without prerelease markers.
+        prerelease_type: Prerelease label (e.g. alpha, beta, rc).
+        prerelease_number: Optional prerelease number (e.g. PR number for alpha123).
+        build_number: Build identifier for prerelease builds.
+    """
+
+    scheme: ArtifactVersionScheme
+    version_override: str | None
+    is_full_release: bool
+    prerelease_type: PrereleaseType
+    prerelease_number: int | None
+    build_number: int | None
+
+
+_PEP440_PRERELEASE_MARKERS: dict[PrereleaseType, str] = {
+    PrereleaseType.alpha: 'a',
+    PrereleaseType.beta: 'b',
+    PrereleaseType.rc: 'rc',
+}
+
+
+def compute_artifact_version(artifact_input: ArtifactVersionInput) -> str:
+    """Compute an artifact version string.
+
+    Args:
+        artifact_input: The inputs for computing the version.
+
+    Returns:
+        The version string to apply to the artifact.
+
+    Raises:
+        BuildNumberRequiredError: If a prerelease build is missing a build number.
+        ReleezError: If git or git-cliff are unavailable, or git-cliff fails.
+    """
+    next_version = artifact_input.version_override or _compute_next_version()
+    if artifact_input.is_full_release:
+        return next_version
+
+    if artifact_input.build_number is None:
+        raise BuildNumberRequiredError
+
+    prerelease_type = artifact_input.prerelease_type.value
+    prerelease_number = artifact_input.prerelease_number
+    if prerelease_number is None:
+        raise PrereleaseNumberRequiredError
+    if artifact_input.scheme == ArtifactVersionScheme.semver:
+        return f'{next_version}-{prerelease_type}{prerelease_number}+{artifact_input.build_number}'
+    if artifact_input.scheme == ArtifactVersionScheme.docker:
+        return f'{next_version}-{prerelease_type}{prerelease_number}-{artifact_input.build_number}'
+    return _pep440_version(
+        next_version=next_version,
+        prerelease_type=artifact_input.prerelease_type,
+        prerelease_number=prerelease_number,
+        build_number=artifact_input.build_number,
+    )
+
+
+def _compute_next_version() -> str:
+    _, info = open_repo()
+    cliff = GitCliff(repo_root=info.root)
+    return cliff.compute_next_version(bump='auto')
+
+
+def _pep440_version(
+    *,
+    next_version: str,
+    prerelease_type: PrereleaseType,
+    prerelease_number: int | None,
+    build_number: int,
+) -> str:
+    marker = _PEP440_PRERELEASE_MARKERS[prerelease_type]
+    return f'{next_version}{marker}{prerelease_number}.dev{build_number}'