Houndarr Changelog

Houndarr changelog conventions

The audience is self-hosters and homelab operators running Houndarr in Docker or Kubernetes alongside the *arr stack. They read config files, env vars, log lines, and SQLite schemas; they do not read the Python source. Tune every bullet for that reader.

Voice (noun-led, present tense)

The category heading carries the verb (### Added, ### Fixed, ### Changed). Bullets describe the post-change state from the reader's vantage point, not the maintainer's action:

• Good: Logs page distinguishes a fresh install (No log entries yet) from a filter that matches nothing (No entries match those filters.). (#566)
• Avoid: We added a fresh-install vs filter-empty distinction to the logs page. (narrator voice)
• Avoid: Distinguish fresh-install from filter-empty on the logs page. (imperative; reserved for SDK changelogs)

This matches the convention used by Authelia, AdGuard Home, Plausible, Caddy, and other self-hosted tools targeting the same audience.

Length

• Target: 80 to 160 characters per bullet.
• Hard ceiling: 250 characters. A bullet longer than that must split into two unrelated bullets, or the second clause moves to the PR body.
• One sentence per bullet. A second sentence is permitted only when a migration or upgrade-affecting consequence must ride with the change (rare).

Vocabulary the operator can act on, only

• Use: env var names (HOUNDARR_COOKIE_SAMESITE), config keys, schema version numbers (Schema v16), database column names that survive in the SQLite file (monitored_total, whisparr_episode), HTTP routes (/api/status), log strings the operator can grep (hourly limit reached (N/hr)), CVE IDs, dependency versions when a security or behaviour change ties to the bump.
• Avoid: internal Python class names (InstanceValidationError, AuthMiddleware._dispatch_proxy), private helpers (_redirect_guard, _run_search_pass), file paths under src/, module attribute names that have no user surface. Describe the user-visible behaviour instead.
• Borderline: public library types that surface in tracebacks (httpx.TransportError). Allowed when the user actually sees the type name in their logs, otherwise paraphrase to "transport-level error".

Banned phrasings (drift signals; rewrite or drop)

• Vague: "Various bug fixes", "Minor improvements", "Misc updates", "Bug fixes and stability improvements".
• Marketing: "We are thrilled to...", "delightful new experience", "groundbreaking", "exciting".
• Magic adverbs without measurement: "seamlessly", "robustly", "significantly", "dramatically". Either quantify ("reduces idle CPU by 60%") or omit.
• Empty verbs: "leverages", "utilizes", "harnesses", "facilitates". Pick the concrete verb.
• Vague comparatives: "Improved error handling", "Enhanced UX", "Better performance". Name the change: "Connection errors now log at WARNING with the instance name."
• Bold lead-ins: **Performance:** faster X. Plain bullet.
• Marketing trail clauses: "for a smoother experience". Stop at the technical fact.
• Past-tense narration: "We added...", "We fixed...". Drop the pronoun.
• Em dashes anywhere (project-wide rule; use a colon, semicolon, comma, period, or parentheses).

What does NOT belong in the changelog

• Pure refactors with no user-visible behaviour change (Common Changelog explicitly excludes these; they live in PR bodies).
• Test-only changes.
• Docs-only changes (the docs site has its own deploy log).
• CI / workflow changes that do not affect deployers. Note the qualifier: a workflow change that alters what a release ships (signatures, attestations, published assets, image contents) does reach deployers and is bulleted.
• Dependency bumps with no security or behaviour impact.

Schema version bumps

When a release ships a SQLite schema migration, name the schema number, what the migration touches, and any rollback constraint. An AdGuard-Home-style "to roll back, downgrade to <previous tag>" line helps operators who restore from a backup.

Examples (verbatim from the repo, judged)

• Exemplary: Helm chart `appVersion` is now prefixed with `v` so it matches the published Docker image tags. (#364) (102 chars; named user-visible attribute; one causal clause).
• Exemplary: Hourly rate-limit skip rows now read `hourly limit reached (N/hr)` across missing, cutoff, and upgrade passes. (#491) (names the exact log string the operator greps for).
• Over-technical (rewrite before merging): Curated `InstanceValidationError.public_message` text replaces the raw exception in instance validation banners should read Instance validation banner shows a curated message instead of the raw Python exception.
• Over-technical (rewrite): Random search order now uses a stratified-shuffle page deck plus partial-page sentinel padding should read Random search order spreads dispatch probability uniformly across the backlog so no page is over- or under-selected.