git-epic 0.1.0__py3-none-any.whl

git_epic/__init__.py

@@ -0,0 +1,3 @@
+"""Epic-based Git workflows."""
+
+__version__ = "0.1.0"

git_epic/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+raise SystemExit(main())

git_epic/cli.py

@@ -0,0 +1,56 @@
+"""Command-line entry point, available as git-epic and git epic."""
+
+import argparse
+import sys
+
+from . import __version__, workflow
+from .process import EpicError
+
+
+def parser() -> argparse.ArgumentParser:
+    root = argparse.ArgumentParser(
+        prog="git epic", description="Epic-based Git workflows and GitLab merge requests"
+    )
+    root.add_argument("--version", "-V", action="version", version=__version__)
+    commands = root.add_subparsers(dest="command", required=True)
+    init = commands.add_parser("init", help="Configure this repository")
+    init.add_argument("--production", default="production", metavar="BRANCH")
+    init.add_argument("--remote", default="origin")
+    start = commands.add_parser("start", help="Create an epic from latest production")
+    start.add_argument("name")
+    task = commands.add_parser("task", help="Work on tasks within an epic")
+    tasks = task.add_subparsers(dest="task_command", required=True)
+    task_start = tasks.add_parser("start", help="Create a task from the current epic")
+    task_start.add_argument("name")
+    tasks.add_parser("submit", help="Push the task and create or return its epic MR")
+    commands.add_parser("sync", help="Merge latest production into the current epic")
+    commands.add_parser("status", help="Show branch context, production drift, MRs, and CI")
+    commands.add_parser(
+        "release",
+        help="Push the epic and create or return its production MR; never merge or deploy",
+    )
+    return root
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = parser().parse_args(argv)
+    try:
+        if args.command == "init":
+            workflow.init(args.production, args.remote)
+        elif args.command == "start":
+            workflow.start(args.name)
+        elif args.command == "task":
+            if args.task_command == "start":
+                workflow.task_start(args.name)
+            else:
+                workflow.task_submit()
+        else:
+            {"sync": workflow.sync, "status": workflow.status, "release": workflow.release}[
+                args.command
+            ]()
+    except (EpicError, OSError) as error:
+        print(f"git-epic: {error}", file=sys.stderr)
+        return 1
+    except KeyboardInterrupt:
+        return 130
+    return 0

git_epic/config.py

@@ -0,0 +1,55 @@
+"""Shared repository settings; credentials remain managed by Git and glab."""
+
+import json
+from dataclasses import asdict, dataclass
+
+from .git import Git
+from .process import EpicError
+
+CONFIG_FILE = ".git-epic.json"
+
+
+@dataclass(frozen=True)
+class Config:
+    production_branch: str = "production"
+    remote: str = "origin"
+    hosting: str = "gitlab"
+
+    def validate(self, git: Git) -> None:
+        git.validate_branch(self.production_branch)
+        git.validate_remote(self.remote)
+
+
+def load_config(git: Git) -> Config:
+    path = git.root / CONFIG_FILE
+    if not path.exists():
+        raise EpicError("Run git epic init first.")
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except json.JSONDecodeError as error:
+        raise EpicError(f"Invalid {CONFIG_FILE}: {error.msg}.") from error
+    if (
+        not isinstance(data, dict)
+        or not isinstance(data.get("productionBranch"), str)
+        or not isinstance(data.get("remote"), str)
+        or data.get("hosting") != "gitlab"
+    ):
+        raise EpicError(
+            f"Invalid {CONFIG_FILE}: expected productionBranch, remote, and hosting: gitlab."
+        )
+    config = Config(data["productionBranch"], data["remote"])
+    config.validate(git)
+    return config
+
+
+def save_config(git: Git, config: Config) -> None:
+    path = git.root / CONFIG_FILE
+    if path.exists():
+        raise EpicError(f"{CONFIG_FILE} already exists. Edit it to change configuration.")
+    config.validate(git)
+    git.fetch(config.remote)
+    git.remote_ref(config.remote, config.production_branch)
+    data = asdict(config)
+    data["productionBranch"] = data.pop("production_branch")
+    with path.open("x", encoding="utf-8") as file:
+        file.write(json.dumps(data, indent=2) + "\n")

git_epic/git.py

@@ -0,0 +1,74 @@
+"""Git operations used by the workflow."""
+
+from dataclasses import dataclass
+from pathlib import Path
+
+from .process import EpicError, run
+
+
+@dataclass(frozen=True)
+class Divergence:
+    behind: int
+    ahead: int
+
+
+class Git:
+    def __init__(self, cwd: Path | None = None):
+        self.root = Path(run("git", ["rev-parse", "--show-toplevel"], cwd or Path.cwd()))
+
+    def exec(self, *args: str) -> str:
+        return run("git", list(args), self.root)
+
+    def dirty(self) -> bool:
+        return bool(
+            self.exec("status", "--porcelain", "--untracked-files=all", "--ignore-submodules=none")
+        )
+
+    def clean(self) -> None:
+        if self.dirty():
+            raise EpicError("Working tree has uncommitted changes. Commit or stash them first.")
+        if any(self.exists(ref) for ref in ("MERGE_HEAD", "CHERRY_PICK_HEAD", "REVERT_HEAD")):
+            raise EpicError("Finish the in-progress Git operation first.")
+        for state in ("rebase-merge", "rebase-apply", "sequencer"):
+            path = self.exec("rev-parse", "--path-format=absolute", "--git-path", state)
+            if Path(path).exists():
+                raise EpicError("Finish the in-progress Git operation first.")
+
+    def branch(self) -> str:
+        branch = self.exec("branch", "--show-current")
+        if not branch:
+            raise EpicError("Detached HEAD: check out an epic or task branch first.")
+        return branch
+
+    def exists(self, ref: str) -> bool:
+        try:
+            self.exec("rev-parse", "--verify", "--quiet", ref)
+        except EpicError:
+            return False
+        return True
+
+    def validate_branch(self, branch: str) -> None:
+        self.exec("check-ref-format", "--branch", branch)
+
+    def validate_remote(self, remote: str) -> None:
+        if remote.startswith("-") or remote not in self.exec("remote").splitlines():
+            raise EpicError(f"Remote '{remote}' does not exist or has an unsupported name.")
+
+    def fetch(self, remote: str) -> None:
+        self.exec("fetch", "--prune", remote, f"+refs/heads/*:refs/remotes/{remote}/*")
+
+    def remote_ref(self, remote: str, branch: str) -> str:
+        ref = f"refs/remotes/{remote}/{branch}"
+        if not self.exists(ref):
+            raise EpicError(f"Branch '{branch}' does not exist on '{remote}'.")
+        return ref
+
+    def create(self, branch: str, base: str, remote: str) -> None:
+        self.validate_branch(branch)
+        if self.exists(f"refs/heads/{branch}") or self.exists(f"refs/remotes/{remote}/{branch}"):
+            raise EpicError(f"Branch '{branch}' already exists. Check it out instead.")
+        self.exec("switch", "--no-track", "-c", branch, base)
+
+    def divergence(self, base: str, head: str = "HEAD") -> Divergence:
+        behind, ahead = self.exec("rev-list", "--left-right", "--count", f"{base}...{head}").split()
+        return Divergence(int(behind), int(ahead))

git_epic/gitlab.py

@@ -0,0 +1,109 @@
+"""GitLab merge requests through the authenticated glab CLI."""
+
+import json
+from dataclasses import dataclass
+from typing import Any
+
+from .git import Git
+from .process import EpicError, run
+
+
+@dataclass(frozen=True)
+class MergeRequest:
+    iid: int
+    web_url: str
+    source_branch: str
+    target_branch: str
+    source_project_id: int
+    pipeline_status: str
+
+    @classmethod
+    def from_json(cls, data: Any) -> "MergeRequest":
+        if not isinstance(data, dict):
+            raise EpicError("Unexpected merge-request response from glab.")
+        for field in ("iid", "source_project_id"):
+            if type(data.get(field)) is not int:
+                raise EpicError(f"Unexpected merge-request {field} from glab.")
+        for field in ("web_url", "source_branch", "target_branch"):
+            if not isinstance(data.get(field), str):
+                raise EpicError(f"Unexpected merge-request {field} from glab.")
+        pipeline = data.get("head_pipeline") or {}
+        status = pipeline.get("status") if isinstance(pipeline, dict) else None
+        return cls(
+            data["iid"],
+            data["web_url"],
+            data["source_branch"],
+            data["target_branch"],
+            data["source_project_id"],
+            status or "no pipeline reported",
+        )
+
+
+class GitLab:
+    def __init__(self, git: Git, remote: str):
+        self.git = git
+        self.repo = git.exec("config", "--get", f"remote.{remote}.url")
+        self._project_id: int | None = None
+
+    def exec(self, *args: str) -> str:
+        return run("glab", [*args, "--repo", self.repo], self.git.root)
+
+    @staticmethod
+    def decode(output: str) -> Any:
+        try:
+            return json.loads(output)
+        except json.JSONDecodeError as error:
+            raise EpicError("Unexpected JSON response from glab.") from error
+
+    def project_id(self) -> int:
+        if self._project_id is None:
+            project = self.decode(
+                run("glab", ["repo", "view", self.repo, "--output", "json"], self.git.root)
+            )
+            if not isinstance(project, dict) or type(project.get("id")) is not int:
+                raise EpicError("Unexpected project response from glab.")
+            self._project_id = project["id"]
+        return self._project_id
+
+    def list(self, source: str | None = None, target: str | None = None) -> list[MergeRequest]:
+        args = ["mr", "list", "--output", "json", "--per-page", "100"]
+        if source:
+            args.extend(["--source-branch", source])
+        if target:
+            args.extend(["--target-branch", target])
+        requests = []
+        page = 1
+        while True:
+            result = self.decode(self.exec(*args, "--page", str(page)))
+            if not isinstance(result, list):
+                raise EpicError("Unexpected merge-request response from glab.")
+            for data in result:
+                mr = MergeRequest.from_json(data)
+                # Deduplication matches our source project; epic status includes fork MRs.
+                if not source or mr.source_project_id == self.project_id():
+                    requests.append(mr)
+            if len(result) < 100:
+                return requests
+            page += 1
+
+    def details(self, iid: int) -> MergeRequest:
+        return MergeRequest.from_json(
+            self.decode(self.exec("mr", "view", str(iid), "--output", "json"))
+        )
+
+    def create(self, source: str, target: str, title: str, description: str) -> str:
+        return self.exec(
+            "mr",
+            "create",
+            "--head",
+            self.repo,
+            "--source-branch",
+            source,
+            "--target-branch",
+            target,
+            "--title",
+            title,
+            "--description",
+            description,
+            "--yes",
+        )

git_epic/process.py

@@ -0,0 +1,30 @@
+"""Shell-free execution of Git and glab."""
+
+import os
+import subprocess
+from pathlib import Path
+
+
+class EpicError(RuntimeError):
+    """An actionable workflow or subprocess failure."""
+
+
+def run(command: str, args: list[str], cwd: Path) -> str:
+    try:
+        result = subprocess.run(
+            [command, *args],
+            cwd=cwd,
+            text=True,
+            encoding="utf-8",
+            errors="replace",
+            capture_output=True,
+            env={**os.environ, "GLAB_CHECK_UPDATE": "false", "GIT_TERMINAL_PROMPT": "0"},
+        )
+    except OSError as error:
+        raise EpicError(
+            f"Cannot run {command}: {error}. Ensure it is installed and on PATH."
+        ) from error
+    if result.returncode:
+        detail = result.stderr.strip() or result.stdout.strip() or f"exit {result.returncode}"
+        raise EpicError(f"{command} {args[0] if args else ''} failed:\n{detail}")
+    return result.stdout.strip()

git_epic/workflow.py

@@ -0,0 +1,178 @@
+"""Team branching and MR workflow. QA and deployments remain external."""
+
+import re
+
+from .config import CONFIG_FILE, Config, load_config, save_config
+from .git import Git
+from .gitlab import GitLab
+from .process import EpicError
+
+TASK_PATTERN = re.compile(r"task/([^/]+)/([^/]+)")
+
+
+def epic_name(branch: str) -> str:
+    if not branch.startswith("epic/") or not branch[5:] or "/" in branch[5:]:
+        raise EpicError("This command requires an epic/<name> branch.")
+    return branch[5:]
+
+
+def name(value: str) -> str:
+    if not re.fullmatch(r"[a-zA-Z0-9][a-zA-Z0-9._-]*", value):
+        raise EpicError(
+            "Names must start with a letter or number and contain only letters, "
+            "numbers, dots, underscores, or hyphens."
+        )
+    return value
+
+
+def context() -> tuple[Git, Config]:
+    git = Git()
+    return git, load_config(git)
+
+
+def init(production: str = "production", remote: str = "origin") -> None:
+    git = Git()
+    git.clean()
+    save_config(git, Config(production, remote))
+    print(f"Created {CONFIG_FILE}. Commit it so the team shares these settings.")
+
+
+def start(value: str) -> None:
+    git, config = context()
+    branch = f"epic/{name(value)}"
+    git.clean()
+    git.fetch(config.remote)
+    git.create(branch, git.remote_ref(config.remote, config.production_branch), config.remote)
+    print(f"Switched to {branch}.")
+
+
+def task_start(value: str) -> None:
+    git, config = context()
+    parent = f"epic/{epic_name(git.branch())}"
+    branch = f"task/{epic_name(parent)}/{name(value)}"
+    git.clean()
+    git.fetch(config.remote)
+    if git.exists(f"refs/remotes/{config.remote}/{parent}"):
+        git.exec("merge", "--ff-only", git.remote_ref(config.remote, parent))
+    git.create(branch, "HEAD", config.remote)
+    print(f"Switched to {branch}; parent: {parent}.")
+
+
+def sync() -> None:
+    git, config = context()
+    epic_name(git.branch())
+    git.clean()
+    git.fetch(config.remote)
+    try:
+        git.exec("merge", "--no-edit", git.remote_ref(config.remote, config.production_branch))
+    except EpicError as error:
+        raise EpicError(
+            f"{error}\nResolve any conflicts and commit, or use git merge --abort. "
+            "Then rerun git epic sync."
+        ) from error
+    print("Epic synchronized with production. Push it to share the changes.")
+
+
+def submit(source: str, target: str, git: Git, config: Config, *, is_release: bool) -> None:
+    git.clean()
+    git.fetch(config.remote)
+    target_ref = git.remote_ref(config.remote, target)
+    drift = git.divergence(target_ref)
+    if is_release and drift.behind:
+        raise EpicError(
+            "Epic is behind production. Run git epic sync and revalidate "
+            "the updated candidate with QA."
+        )
+    hosting = GitLab(git, config.remote)
+    existing = hosting.list(source, target)
+    if not existing and not drift.ahead:
+        raise EpicError(f"No new commits to submit to {target}.")
+    git.exec("push", "--set-upstream", config.remote, f"HEAD:refs/heads/{source}")
+    if existing:
+        print(f"Existing merge request: {existing[0].web_url}")
+        return
+    if is_release:
+        title = f"Release {epic_name(source)}"
+        description = (
+            f"Release {source} into {target}.\n\n"
+            f"Candidate commit: {git.exec('rev-parse', 'HEAD')}\n\n"
+            "Required CI, reviews, and QA approval must be verified before merging. "
+            "This command does not merge or deploy."
+        )
+    else:
+        title = f"Task: {source.split('/')[-1]}"
+        description = f"Merge {source} into its parent epic {target}."
+    try:
+        print(hosting.create(source, target, title, description))
+    except EpicError as creation_error:
+        # Another teammate may have created the MR between lookup and creation.
+        try:
+            concurrent = hosting.list(source, target)
+        except EpicError:
+            raise creation_error from None
+        if not concurrent:
+            raise
+        print(f"Existing merge request: {concurrent[0].web_url}")
+
+
+def task_submit() -> None:
+    git, config = context()
+    source = git.branch()
+    match = TASK_PATTERN.fullmatch(source)
+    if not match:
+        raise EpicError("This command requires a task/<epic>/<name> branch.")
+    parent = f"epic/{match[1]}"
+    git.clean()
+    git.fetch(config.remote)
+    if not git.exists(f"refs/remotes/{config.remote}/{parent}"):
+        if not git.exists(f"refs/heads/{parent}"):
+            raise EpicError(
+                f"Parent {parent} is missing locally and remotely. Restore or publish it first."
+            )
+        git.exec("push", config.remote, f"refs/heads/{parent}:refs/heads/{parent}")
+        git.fetch(config.remote)
+    submit(source, parent, git, config, is_release=False)
+
+
+def release() -> None:
+    git, config = context()
+    source = git.branch()
+    epic_name(source)
+    submit(source, config.production_branch, git, config, is_release=True)
+
+
+def status() -> None:
+    git, config = context()
+    branch = git.branch()
+    task = TASK_PATTERN.fullmatch(branch)
+    epic = f"epic/{task[1] if task else epic_name(branch)}"
+    git.fetch(config.remote)
+    production_ref = git.remote_ref(config.remote, config.production_branch)
+    print(f"Branch: {branch}\nEpic: {epic}\nProduction: {config.remote}/{config.production_branch}")
+    local_epic = f"refs/heads/{epic}"
+    remote_epic = f"refs/remotes/{config.remote}/{epic}"
+    for label, ref in (
+        ("Local epic vs production", local_epic),
+        ("Remote epic vs production", remote_epic),
+    ):
+        if not git.exists(ref):
+            print(f"{label}: not present")
+            continue
+        drift = git.divergence(production_ref, ref)
+        print(f"{label}: {drift.behind} behind, {drift.ahead} ahead")
+    if git.exists(local_epic) and git.exists(remote_epic):
+        drift = git.divergence(remote_epic, local_epic)
+        print(f"Local epic vs remote epic: {drift.behind} behind, {drift.ahead} ahead")
+    if git.dirty():
+        print("Working tree: uncommitted changes")
+    hosting = GitLab(git, config.remote)
+    requests = hosting.list(branch if task else None, epic)
+    requests.extend(hosting.list(epic, config.production_branch))
+    if not requests:
+        print("No open merge requests for this task/epic.")
+    for mr in requests:
+        details = hosting.details(mr.iid)
+        print(
+            f"MR !{mr.iid}: {mr.source_branch} → {mr.target_branch}\n"
+            f"{mr.web_url}\nCI: {details.pipeline_status}"
+        )

git_epic-0.1.0.dist-info/METADATA

@@ -0,0 +1,205 @@
+Metadata-Version: 2.4
+Name: git-epic
+Version: 0.1.0
+Summary: Epic-based Git workflows and GitLab merge requests
+Author: Wonderteam
+Project-URL: Repository, https://gitlab.wonderbeauties.com/wonderteam/git-epic
+Project-URL: Issues, https://gitlab.wonderbeauties.com/wonderteam/git-epic/-/issues
+Keywords: git,cli,gitlab,epic,workflow
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+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: Topic :: Software Development :: Version Control :: Git
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Provides-Extra: dev
+Requires-Dist: build<2,>=1.2; extra == "dev"
+Requires-Dist: ruff<1,>=0.11; extra == "dev"
+Requires-Dist: twine<7,>=6; extra == "dev"
+
+# git-epic
+
+A Python CLI for our epic-based Git workflow, with no runtime Python dependencies.
+Git discovers the `git-epic`
+executable automatically, so commands use `git epic …`.
+
+## Install
+
+Requires Python 3.11+, Git 2.31+, and [glab](https://gitlab.com/gitlab-org/cli).
+Authenticate once with your GitLab host:
+
+```sh
+glab auth login --hostname gitlab.wonderbeauties.com
+```
+
+After the first PyPI release, install with [pipx](https://pipx.pypa.io/):
+
+```sh
+pipx install git-epic
+pipx ensurepath
+git epic -h
+```
+
+For local development before publication:
+
+```sh
+pipx install .
+pipx ensurepath
+git epic -h
+```
+
+If `ensurepath` changes your PATH, open a new terminal. Upgrade with
+`pipx upgrade git-epic`. The package is not yet published; `pipx install .` works
+from a local checkout today.
+
+## Commands
+
+Use `git epic -h` for CLI help. Git reserves `git epic --help` for a system manual
+page; this MVP does not install one. Direct invocation also supports
+`git-epic --help`.
+
+| Command | Behavior |
+| --- | --- |
+| `git epic init` | Write shared `.git-epic.json`; defaults to `production`, `origin`, and GitLab. |
+| `git epic start <name>` | Fetch production; create and switch to local `epic/<name>`. |
+| `git epic task start <name>` | From an epic, fetch and fast-forward remote epic changes if possible; create `task/<epic>/<name>`. |
+| `git epic task submit` | Push committed task changes; create or return its parent epic MR. Publish the local parent epic if it is not yet on the remote. |
+| `git epic sync` | From an epic, fetch and merge production. Push the result yourself or with `release`. |
+| `git epic status` | Fetch; show current task/epic, labelled local/remote epic drift, related open MRs (including task MRs when on an epic), and their latest reported CI status. |
+| `git epic release` | Push committed epic changes; create or return an MR targeting production. **Never merges or deploys.** |
+
+GitLab calls PRs **merge requests (MRs)**. Submission commands also push new commits
+when returning an existing MR; they do not create a duplicate.
+
+Names are single segments: letters, numbers, dots, underscores, and hyphens, starting
+with a letter or number. Git's branch-name restrictions also apply.
+
+For repositories using a different production branch or remote:
+
+```sh
+git epic init --production main --remote origin
+git add .git-epic.json
+git commit -m "Configure git-epic"
+git push
+```
+
+Commit this file on production before creating epics so all branches and teammates
+inherit it. It contains no credentials. Existing configuration is never overwritten;
+edit the file to change settings. An initial production commit must already exist on
+the remote; `init` does not bootstrap an empty application repository.
+
+## Typical workflow
+
+```sh
+git epic start checkout
+git epic task start payment
+# Implement and commit your task.
+git epic task submit
+# Review, CI, and merge the task MR in GitLab.
+git switch epic/checkout
+# Bring merged tasks into the local epic.
+git fetch origin
+git merge --ff-only origin/epic/checkout
+git epic sync
+git push origin epic/checkout
+# Deploy OTF and obtain QA approval through the existing team process.
+git epic release
+# Review, required CI, and merge in GitLab; CI/CD deploys production.
+```
+
+OTF deployment and QA approval are external to this CLI. Approval belongs to an
+exact commit/build. If the candidate or production changes, update and revalidate
+before merging. `release` refuses an epic that is behind current production, but
+the hosting platform/CI must also enforce release checks at merge time. The CLI
+does not record or verify QA approval.
+
+## Git behavior
+
+- Branch and submission operations require a clean working tree and no unfinished
+  merge/rebase/cherry-pick/revert. `status` allows uncommitted changes.
+- Fetch updates remote-tracking refs. No command force-pushes, resets, deletes a
+  branch, merges an MR, or deploys.
+- `start` creates a local epic. Submission publishes branches with ordinary pushes;
+  non-fast-forward pushes are rejected rather than overwriting teammates' work.
+- `task start` stops if local and remote epic histories have diverged. Reconcile
+  the epic using Git before retrying. `release` similarly requires your local epic
+  to include remote epic work before a push can succeed.
+- If `sync` conflicts, resolve and commit, or use `git merge --abort`.
+- An MR/API failure after a push leaves the branch published; retry the command.
+- GitLab authentication is managed by `glab`, and Git authentication by Git.
+
+## Development and release
+
+```sh
+python3 -m venv .venv
+source .venv/bin/activate
+python -m pip install -e '.[dev]'
+ruff check .
+ruff format --check .
+python -m unittest discover -s tests -v
+python -m build
+python -m twine check --strict dist/*.whl dist/*.tar.gz
+```
+
+Tests create temporary local Git repositories and a fake `glab`; they never create
+real MRs or touch production. GitLab API behavior is delegated to the installed
+`glab`. CI checks Python 3.11 and 3.14, builds a wheel and source distribution,
+validates metadata with Twine, and smoke-tests the installed wheel via Git.
+
+## Publish to PyPI
+
+### Local publication helper
+
+From a clean, committed checkout with a configured Git upstream, run:
+
+```sh
+./publish.sh
+```
+
+The helper uses `uv` to prompt for a PEP 440 version (press Enter to keep the
+current version for the first release), update the version and README release-tag
+examples, run tests, clean and build distributions, validate with Twine, upload
+to PyPI, and commit/push the release changes. Set `PYPI_API_TOKEN` or
+`TWINE_PASSWORD` in your shell; otherwise Twine prompts for authentication.
+It does not create a release tag or trigger the CI publication job.
+
+### GitLab CI publication
+
+The distribution name is **`git-epic`**, import package is **`git_epic`**, and CLI
+entry point is **`git-epic`**. Version is defined once in
+`src/git_epic/__init__.py`.
+
+1. Create a PyPI account and an API token. For the first release, a token with
+   account scope is needed; after creating the project, use a project-scoped token.
+2. In GitLab CI/CD variables, add **`PYPI_API_TOKEN`** as a masked, protected
+   variable. Protect the release tag pattern (`v*`) so tagged jobs can access it.
+3. Update the version, then push a matching tag, for example `v0.1.0`.
+4. After verification and build jobs pass, manually run **`publish:pypi`**.
+
+The job uploads only the validated wheel and source distribution from the build
+job. A release tag must match the package version. PyPI does not allow reusing
+an uploaded version: use a new version for subsequent releases.
+
+An optional **`publish:testpypi`** job uses **`TESTPYPI_API_TOKEN`** and the separate
+TestPyPI registry. TestPyPI accounts and tokens are independent of PyPI. A test
+installation uses `pipx install --index-url https://test.pypi.org/simple/ git-epic`.
+
+For a manual upload of locally built, validated distributions:
+
+```sh
+export TWINE_USERNAME=__token__
+# Set TWINE_PASSWORD to your PyPI API token in your shell.
+python -m twine upload --non-interactive dist/*.whl dist/*.tar.gz
+```
+
+Credentials are supplied by the shell or CI, never stored in project files. PyPI
+Trusted Publishing currently supports GitLab.com, not this self-managed GitLab
+host, so the release jobs use API tokens. Package-name availability is determined
+by PyPI at upload time. A public PyPI release includes the source code even when
+the GitLab repository is private.

git_epic-0.1.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+git_epic/__init__.py,sha256=TaPmkb9usOUgMeLVOsyHpxV_jLvApDluZt-Wkf5ZnXM,55
+git_epic/__main__.py,sha256=k1ocEWawweo1qCJWNFAAvyxz3tcY13dzvCenHszij30,48
+git_epic/cli.py,sha256=nZ5j_ekYdc8BWiSA1UO3GVQZKqkKwt6-ytwsMJzYDNk,2271
+git_epic/config.py,sha256=ljEHqKn94levnqKT-j8Y-CHNm0IZBlCvi1INMa5VJBQ,1774
+git_epic/git.py,sha256=3hHhwnT6wUyAbV3Q5xDRAncfivQzDElc1UJCV1lf0N8,2905
+git_epic/gitlab.py,sha256=rPxoVzEMKawe3q-PsC3v2-igBQko2Sk5CEsZtLeEJ_s,3843
+git_epic/process.py,sha256=cEfNjoNHbGEG7lZk3aJskeJ7QF-9kQ2S2qqX3Lc5Glo,949
+git_epic/workflow.py,sha256=pG1XGPZftFWjcg2xIlWwGKjTpTOSdp9D7I9-qKFV5GM,6544
+git_epic-0.1.0.dist-info/METADATA,sha256=HKnespcLSHQ9c8oYI2Pt2WTu1DaQ8x4PXXc4y7Dse-M,8488
+git_epic-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+git_epic-0.1.0.dist-info/entry_points.txt,sha256=xIHqx8kk4Vsqv-GDrN4d_zKEhKyT3w8bFgDFTJVojfY,47
+git_epic-0.1.0.dist-info/top_level.txt,sha256=32PQr4miBSJjSknOJlMf5aT-3NZ4Bo7g9-kSHmrOux8,9
+git_epic-0.1.0.dist-info/RECORD,,

git_epic-0.1.0.dist-info/WHEEL

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

git_epic-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+git-epic = git_epic.cli:main

git_epic-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+git_epic