esys-gitlog

Python implementation of git elog. The distribution name is esys-gitlog. The import package is esys_gitlog. Installed commands: git-elog (so Git can run git elog) and the shorter alias elog. Prefer elog --help — git elog --help is handled by Git's own help path, not the Typer CLI.

The shared contract lives in esys-gitlog-spec. This repository carries that contract in Python. It does not define a second one.

Smoke

pip install .
elog --help
elog --json

--json writes one QA report document to stdout. The first skeleton returns an empty commits array.

Release / publish

Tag-driven CI publishes to GitLab Package Registry, TestPyPI, then PyPI (Deckicorn-style ADR-0009 flow). See docs/release-pipeline.md.

python scripts/publish_release.py --dry-run --bump patch
python scripts/build_package.py
python scripts/smoke_install_package.py --dist dist --expected-version 0.1.0

Preferences and profiles

Layered tool preferences (user → .tools/esys/esys-gitlog/ → .tools_local/…) and named profiles follow root SADR-0009 / SADR-0010 and contract CADR-0012.

elog --preferences path.json   # preference overlay
elog --profile acme            # built-in or profiles/acme.json
elog --config path/profile.json  # one-off profile file
elog preferences detect        # probe jira-cli/acli + git remote; write missing user keys
elog preferences detect --json --no-write   # machine-readable candidates (extension setup)
elog preferences set-link jira-id 'https://host/browse/{id}'
elog preferences clear-link jira-id
elog preferences set-tool jira 'C:\tools\jira.exe'   # optional absolute path
elog preferences set-tool acli /usr/local/bin/acli

Jira browse bases come from local jira-cli config and/or Atlassian acli (acli jira config get site), never from per-commit HTTP (SADR-0010). Detection only fills unset user keys unless you use set-link. Absolute paths live under detection.jiraExecutable / detection.acliExecutable when the tools are not on PATH.

Live Jira fixture (SCRUM)

The free site libesys.atlassian.net uses project key SCRUM only (do not invent other project keys).

1. Configure acli or jira-cli against that site (optional absolute paths via elog preferences set-tool).
2. Seed once (creates 10 new issues, writes the pin — not part of every CI run):

python scripts/seed_jira_live_fixture.py --project SCRUM --count 10

3. Commit tests/integration/jira_live.pin.json.
4. Materialize a durable Git repo for the VS Code extension / manual checks:

python scripts/materialize_jira_live_repo.py

Output: tests/integration/jira_live_repo/ (gitignored except a placeholder README). Open that folder, store the browse template, refresh the commit browser. 5. Run the live test locally or enable GitLab variable ESYS_GITLOG_JIRA_LIVE=1 for job test:jira-live:

ESYS_GITLOG_JIRA_LIVE=1 pytest -m jira_live -o addopts= --no-cov

Default pytest excludes @pytest.mark.jira_live so coverage stays offline.

Standalone binary (optional)

The primary install remains the wheel + git-elog / elog console scripts. For a frozen one-file binary (for example Cursor esysGitlog.executablePath without a Python env on PATH):

python scripts/build_standalone.py

Output: dist/git-elog.exe (Windows) or dist/git-elog (Linux/macOS). Build on the OS you need — this does not cross-compile.

• Architecture
• ADRs
• ASRs
• Implementation plan