releez 0.2.2__py3-none-any.whl

releez/version_tags.py

@@ -0,0 +1,69 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import StrEnum
+
+from semver import VersionInfo
+
+from releez.errors import InvalidReleaseVersionError
+
+
+class AliasVersions(StrEnum):
+    """Which alias versions to include in addition to the exact version."""
+
+    none = 'none'
+    major = 'major'
+    minor = 'minor'
+
+
+@dataclass(frozen=True)
+class VersionTags:
+    """Computed tags for a release version.
+
+    Attributes:
+        exact: The exact version tag (e.g. `2.3.4`).
+        major: The major tag (e.g. `v2`).
+        minor: The major.minor tag (e.g. `v2.3`).
+    """
+
+    exact: str
+    major: str
+    minor: str
+
+
+def compute_version_tags(*, version: str) -> VersionTags:
+    """Compute exact/major/minor tags for a full release version.
+
+    Args:
+        version: The full release version (`x.y.z`).
+
+    Returns:
+        The computed tag strings.
+
+    Raises:
+        InvalidReleaseVersionError: If the version is not a full `x.y.z` release.
+    """
+    normalized = version.strip().removeprefix('v')
+
+    try:
+        parsed = VersionInfo.parse(normalized)
+    except ValueError as exc:
+        raise InvalidReleaseVersionError(version) from exc
+
+    if parsed.prerelease is not None or parsed.build is not None:
+        raise InvalidReleaseVersionError(version)
+
+    return VersionTags(
+        exact=normalized,
+        major=f'v{parsed.major}',
+        minor=f'v{parsed.major}.{parsed.minor}',
+    )
+
+
+def select_tags(*, tags: VersionTags, aliases: AliasVersions) -> list[str]:
+    """Select which version aliases to output/publish given an alias level."""
+    if aliases == AliasVersions.none:
+        return [tags.exact]
+    if aliases == AliasVersions.major:
+        return [tags.exact, tags.major]
+    return [tags.exact, tags.major, tags.minor]

releez-0.2.2.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,18 @@
+releez/__init__.py,sha256=U4S_2y3zgLZVfMenHRaJFBW8yqh2mUBuI291LGQVOJ8,35
+releez/artifact_version.py,sha256=sXHjR4GyDyRabYbTVINi1WEaeaoyiyrKE5BjPZHohvc,3386
+releez/cli.py,sha256=pnR6M6b0x2p-cYCVqCULKtrgpnox7fJf6UKutmIU36E,17005
+releez/cliff.py,sha256=fVHyFTdrxuraZiuWW8KEWXvbRBAR_HdPJyGHLG9V-vM,5080
+releez/errors.py,sha256=LVLrGtkr1gfScwwXUnlNI-kSyVBmW5nNHLXofCGFMV4,7104
+releez/git_repo.py,sha256=_Np11E0LUfWutSGapzLcCclk9NT5D30SEQCTzZXF8N8,6245
+releez/github.py,sha256=c-9soa457X8HzaeVM3JJcpdWzMjl_ZbQH7VN-3jx09w,3885
+releez/process.py,sha256=4I-sZNDCqTG167K9xglrzhd16pPihd6jI_4wyQ4UmCw,1416
+releez/release.py,sha256=TKLEsVgvvgmn_js5T8aqtoc19fTjOJI9DmgXYjkO95U,6819
+releez/settings.py,sha256=eOelkqCFetZdmOPCfaNxoxHvfn3zRQtb84PUztb09Pg,2953
+releez/subapps/__init__.py,sha256=pDyHecbnvOayItqUw2FFVET4H7Lj4glgTqUgMrL-S34,116
+releez/subapps/changelog.py,sha256=rJpdzJocYNDzjL8YJFw0v6LyNYLtJvsxZUu3f3eIi_I,2594
+releez/utils.py,sha256=19PYyrUXPYLAgvD14Q7taZMlctV7YyLT0MAtVhmn18M,1356
+releez/version_tags.py,sha256=nnkdnwYADO-9tt2vYT7xAbitBFvQPUkgxvdtRVY10C0,1798
+releez-0.2.2.dist-info/WHEEL,sha256=fAguSjoiATBe7TNBkJwOjyL1Tt4wwiaQGtNtjRPNMQA,80
+releez-0.2.2.dist-info/entry_points.txt,sha256=dFRzNkEp1RC4HgqbeI7XAHDPbIkL9-7KWvp28dj_ctw,44
+releez-0.2.2.dist-info/METADATA,sha256=MzGAxuPDzdV-G7RBMj202YLELvmeQ0ewN8EpNdjOG_k,6938
+releez-0.2.2.dist-info/RECORD,,

releez-0.2.2.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: uv 0.9.28
+Root-Is-Purelib: true
+Tag: py3-none-any

releez-0.2.2.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+releez = releez.cli:main
+