README
¶
Patchlog
Patchlog is a safe release coordinator for protected Git repositories. It turns commit history into a fingerprinted release plan, prepares an isolated version-bump branch for review, then tags only the exact green commit merged to the protected branch.
Safe protected release
From a clean repository with a version file:
# Universal immutable plan. It prints an exact approval fingerprint.
patchlog release --dry-run
# Apply only that approved plan: create, commit, and push release/vX.Y.Z.
patchlog release prepare --approve sha256:<fingerprint>
Open the pull request, require green CI, merge it, and wait for post-merge CI on the protected branch. Patchlog then detects the finalize phase:
patchlog release --dry-run
patchlog release finalize --approve sha256:<fingerprint>
Finalize revalidates that local and remote protected-branch commits match, creates an annotated tag on that exact commit, and pushes only the immutable tag. The default path does not call AI, write analytics, contact Confluence, or combine optional extensions with the protected transaction.
Install
With Go 1.22 or newer:
go install github.com/fxdv/patchlog/cmd/patchlog@latest
patchlog --version
Release archives and SHA256SUMS are published on the GitHub releases page. Archives also receive signed Sigstore provenance attestations, verifiable with gh attestation verify <archive> --repo fxdv/patchlog.
Homebrew is live and installation-tested automatically:
brew tap fxdv/tap
brew install patchlog
patchlog --version
The fxdv/homebrew-tap synchronizes the checksum-pinned formula from stable Patchlog releases and installs/tests it before committing an update. The Patchlog release workflow independently tests the published formula on macOS. Scoop remains a planned second channel.
Read-only notes
patchlog --from v0.1.0 --to HEAD
Plain patchlog is reporting-only. Optional capabilities use focused
subcommands:
patchlog ai
patchlog confluence
patchlog metrics
patchlog labs --gamify
Direct commit/tag/push remains available only as the explicit
patchlog release direct compatibility workflow.
Documentation
- Quick start
- Configuration and security
- Advanced workflows
- 0.2.0 stability contract
- Product measurements
- Real-repository evidence
- Package-manager publishing
- Complete CLI and feature reference
- Security policy
Development
bash scripts/gate.sh
The gate runs formatting, vet, build, race-enabled package tests, integration tests, and orchestration E2E tests. CI also uploads coverage for cmd/patchlog, internal, and pkg; coverage is diagnostic and is not a release gate.
License
MIT — see LICENSE.
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
patchlog
command
|
|
|
internal
|
|
|
atomicfile
Package atomicfile provides recoverable same-directory file replacement.
|
Package atomicfile provides recoverable same-directory file replacement. |
|
pkg
|
|
|
ai
Package ai provides AI provider clients (Ollama, OpenAI, Anthropic) for prose generation, description enhancement, and metric interpretation.
|
Package ai provides AI provider clients (Ollama, OpenAI, Anthropic) for prose generation, description enhancement, and metric interpretation. |
|
audit
Package audit compares a changelog file against git history to find missing or stale entries.
|
Package audit compares a changelog file against git history to find missing or stale entries. |
|
bump
Package bump handles semantic version bumping in package.json, Cargo.toml, pyproject.toml, and plain text version files.
|
Package bump handles semantic version bumping in package.json, Cargo.toml, pyproject.toml, and plain text version files. |
|
cache
Package cache provides a file-based JSON cache with TTL for Jira issues and Confluence page lookups.
|
Package cache provides a file-based JSON cache with TTL for Jira issues and Confluence page lookups. |
|
classify
Package classify assigns significance levels (skip/patch/minor/major) to commits based on diff analysis.
|
Package classify assigns significance levels (skip/patch/minor/major) to commits based on diff analysis. |
|
commit
Package commit parses conventional commit messages into structured data with type, scope, breaking flag, and Jira keys.
|
Package commit parses conventional commit messages into structured data with type, scope, breaking flag, and Jira keys. |
|
confluence
Package confluence provides a Confluence Cloud/Server API client for creating, updating, and enriching release note pages with analytics panels, charts, gamification, and trends dashboards.
|
Package confluence provides a Confluence Cloud/Server API client for creating, updating, and enriching release note pages with analytics panels, charts, gamification, and trends dashboards. |
|
console
Package console provides terminal output utilities: spinners, colored text, and release summary formatting.
|
Package console provides terminal output utilities: spinners, colored text, and release summary formatting. |
|
curate
Package curate provides an interactive terminal UI for curating release notes before publishing.
|
Package curate provides an interactive terminal UI for curating release notes before publishing. |
|
deps
Package deps detects dependency version bumps in manifest files and fetches upstream changelogs.
|
Package deps detects dependency version bumps in manifest files and fetches upstream changelogs. |
|
dpi
Package dpi computes a Developer Productivity Index (0-100) per contributor based on velocity, quality, impact, and consistency.
|
Package dpi computes a Developer Productivity Index (0-100) per contributor based on velocity, quality, impact, and consistency. |
|
drift
Package drift compares planned Jira tickets against delivered commits to measure plan-vs-actual gap.
|
Package drift compares planned Jira tickets against delivered commits to measure plan-vs-actual gap. |
|
gamify
Package gamify computes contributor achievements, badges, and levels for release gamification.
|
Package gamify computes contributor achievements, badges, and levels for release gamification. |
|
gitlog
Package gitlog provides git history fetching via subprocess calls, including commit logs, diff stats, changed files, and tag queries.
|
Package gitlog provides git history fetching via subprocess calls, including commit logs, diff stats, changed files, and tag queries. |
|
gittag
Package gittag handles git tag creation, commit staging, and remote push for release automation.
|
Package gittag handles git tag creation, commit staging, and remote push for release automation. |
|
gitwiki
Package gitwiki provides a GitLab wiki API client for changelog accumulation.
|
Package gitwiki provides a GitLab wiki API client for changelog accumulation. |
|
health
Package health analyzes team health signals: workload balance, after-hours work, release contribution concentration, burnout indicators.
|
Package health analyzes team health signals: workload balance, after-hours work, release contribution concentration, burnout indicators. |
|
htmlreport
Package htmlreport generates standalone HTML reports with metric tables, tooltips, DPI, health signals, and ownership heatmaps.
|
Package htmlreport generates standalone HTML reports with metric tables, tooltips, DPI, health signals, and ownership heatmaps. |
|
httpclient
Package httpclient provides HTTP clients with connection pooling and retry with exponential backoff.
|
Package httpclient provides HTTP clients with connection pooling and retry with exponential backoff. |
|
i18n
Package i18n provides section heading translations and AI prompt localization for en, ru, and zh.
|
Package i18n provides section heading translations and AI prompt localization for en, ru, and zh. |
|
infer
Package infer uses AI to classify uncategorized commits into conventional commit types.
|
Package infer uses AI to classify uncategorized commits into conventional commit types. |
|
jira
Package jira provides a Jira Cloud/Server API client for fetching issue details concurrently with caching support.
|
Package jira provides a Jira Cloud/Server API client for fetching issue details concurrently with caching support. |
|
lint
Package lint validates commits against conventional commit standards with optional AI suggestions.
|
Package lint validates commits against conventional commit standards with optional AI suggestions. |
|
multirepo
Package multirepo aggregates changelogs from multiple repositories into a single document.
|
Package multirepo aggregates changelogs from multiple repositories into a single document. |
|
ownership
Package ownership computes code ownership heatmaps from commit history per directory and file.
|
Package ownership computes code ownership heatmaps from commit history per directory and file. |
|
postmortem
Package postmortem analyzes post-release stability by detecting rollbacks, hotfixes, and regressions.
|
Package postmortem analyzes post-release stability by detecting rollbacks, hotfixes, and regressions. |
|
render
Package render provides markdown, JSON, and changelog output rendering for release reports.
|
Package render provides markdown, JSON, and changelog output rendering for release reports. |
|
safehtml
Package safehtml is the sole boundary for inserting untrusted text into HTML.
|
Package safehtml is the sole boundary for inserting untrusted text into HTML. |
|
semantic
Package semantic generates AI-powered semantic summaries of actual code diffs per release section.
|
Package semantic generates AI-powered semantic summaries of actual code diffs per release section. |
|
significance
Package significance defines significance levels (skip, patch, minor, major) for commit classification.
|
Package significance defines significance levels (skip, patch, minor, major) for commit classification. |
|
theme
Package theme uses AI to group commits into thematic sections instead of conventional commit types.
|
Package theme uses AI to group commits into thematic sections instead of conventional commit types. |
|
timeline
Package timeline renders a release history table with key metrics for cross-release comparison.
|
Package timeline renders a release history table with key metrics for cross-release comparison. |
Click to show internal directories.
Click to hide internal directories.