v2.4.0: init scaffolding, dep --requirements, mkdocs plugin

Author: Londopy

CHANGELOG.md

@@ -2,6 +2,18 @@
 
 Parse, query, and validate changelogs in Python and CI.
 
+## [2.4.0] - 2026-07-19
+
+### Added
+
+- `patchnotes init` scaffolds a spec-compliant starter CHANGELOG.md (strict-validation clean out of the box); `--workflow` also writes a ready-made `.github/workflows/changelog.yml` PR check.
+- `dep --requirements old.txt new.txt` diffs two requirements files and runs the breaking/security analysis for every changed pin at once — built for reviewing lockfile bump PRs. With `--strict`, flagged changes fail CI.
+- mkdocs plugin: add `patchnotes` to `plugins:` in mkdocs.yml and a `<!-- patchnotes -->` marker in any docs page renders the styled changelog at build time (`pip install patchnotes[mkdocs]`).
+
+### Fixed
+
+- An empty [Unreleased] section no longer triggers a PN203 warning — it's the normal state right after a release (and what `bump` leaves behind). Empty *versioned* releases still warn.
+
 ## [2.3.0] - 2026-07-19
 
 ### Added

README.md

@@ -34,6 +34,10 @@ pip install patchnotes
 
 Requires Python 3.10+.
 
+Starting a new project? `patchnotes init` creates a spec-compliant starter
+changelog, and `patchnotes init --workflow` adds a ready-made PR validation
+workflow too.
+
 ---
 
 ## Usage
@@ -268,6 +272,14 @@ changelog, and flags breaking/removed/security/deprecated entries in the
 version range. `--all` shows everything; `--format json` for scripting.
 Best-effort: needs the dependency to keep a parseable changelog.
 
+Reviewing a whole lockfile bump? Diff two requirements files at once:
+
+```bash
+patchnotes dep --requirements old-requirements.txt requirements.txt
+# analyzes every changed pin, lists added/removed packages,
+# and with --strict exits 1 if anything breaking/security is flagged
+```
+
 ---
 
 ## Rendering
@@ -482,6 +494,22 @@ This repository dogfoods all of it: [`ci.yml`](.github/workflows/ci.yml) validat
 
 ---
 
+## mkdocs
+
+Render the changelog into your documentation site (`pip install patchnotes[mkdocs]`):
+
+```yaml
+# mkdocs.yml
+plugins:
+  - patchnotes:
+      file: CHANGELOG.md
+```
+
+Then put `<!-- patchnotes -->` in any docs page — it's replaced with the
+parsed, styled changelog at build time.
+
+---
+
 ## pre-commit
 
 Validate (or auto-fix) the changelog on every commit:

patchnotes/__init__.py

@@ -63,7 +63,7 @@
     register_format,
 )
 
-__version__ = "2.3.0"
+__version__ = "2.4.0"
 __all__ = [
     "parse",
     "parse_file",

patchnotes/_cli.py

@@ -44,8 +44,9 @@
     "fix": (0, 0),
     "check-version": (0, 0),
     "fragment": (1, 3),
-    "dep": (3, 3),
+    "dep": (1, 3),
     "badge": (0, 0),
+    "init": (0, 0),
 }
 
 #: commands that accept an optional trailing file argument
@@ -153,6 +154,17 @@ def main(argv=None) -> int:
         help="Fragments directory (default: changelog.d/ next to the "
         "changelog)",
     )
+    parser.add_argument(
+        "--requirements",
+        action="store_true",
+        help="With 'dep': compare two requirements files instead of one "
+        "package (dep --requirements old.txt new.txt)",
+    )
+    parser.add_argument(
+        "--workflow",
+        action="store_true",
+        help="With 'init': also scaffold .github/workflows/changelog.yml",
+    )
     parser.add_argument(
         "--all",
         action="store_true",
@@ -204,6 +216,8 @@ def main(argv=None) -> int:
     if args.format == "sarif" and args.command != "validate":
         parser.error("--format sarif is only supported with 'validate'")
 
+    if args.command == "init":
+        return _cmd_init(args)
     if args.command == "dep":
         return _cmd_dep(args)
     if args.command == "fragment":
@@ -590,7 +604,40 @@ def _cmd_fragment(args) -> int:
     return EXIT_USAGE
 
 
+def _cmd_init(args) -> int:
+    from ._scaffold import write_changelog, write_workflow
+
+    try:
+        write_changelog(args.file, repo_url=args.repo_url)
+    except FileExistsError as e:
+        print(f"Error: {e}", file=sys.stderr)
+        return EXIT_FAIL
+    created = [args.file]
+    if args.workflow:
+        try:
+            created.append(write_workflow(args.file))
+        except FileExistsError as e:
+            print(f"Warning: {e}", file=sys.stderr)
+    if not args.quiet:
+        for path in created:
+            print(f"Created {path}")
+        print("Next: add entries under [Unreleased], then "
+              f"`patchnotes {args.file} bump X.Y.Z` on release day.")
+    return EXIT_OK
+
+
 def _cmd_dep(args) -> int:
+    if args.requirements:
+        if len(args.params) != 2:
+            print("Usage: patchnotes dep --requirements OLD.txt NEW.txt",
+                  file=sys.stderr)
+            return EXIT_USAGE
+        return _cmd_dep_requirements(args)
+    if len(args.params) != 3:
+        print("Usage: patchnotes dep PACKAGE FROM_VERSION TO_VERSION",
+              file=sys.stderr)
+        return EXIT_USAGE
+
     from ._depdiff import fetch_dep_changelog, find_github_repo, render_dep_diff
 
     package, from_v, to_v = args.params
@@ -622,6 +669,80 @@ def _cmd_dep(args) -> int:
         ))
     else:
         print(text)
+    if args.strict and flagged:
+        return EXIT_FAIL
+    return EXIT_OK
+
+
+def _cmd_dep_requirements(args) -> int:
+    from ._depdiff import (
+        diff_requirements,
+        fetch_dep_changelog,
+        find_github_repo,
+        render_dep_diff,
+    )
+
+    old_path, new_path = args.params
+    try:
+        with open(old_path, "r", encoding="utf-8") as fh:
+            old_text = fh.read()
+        with open(new_path, "r", encoding="utf-8") as fh:
+            new_text = fh.read()
+    except OSError as e:
+        print(f"Error: {e}", file=sys.stderr)
+        return EXIT_USAGE
+
+    changed, added, removed = diff_requirements(old_text, new_text)
+    total_flagged = 0
+    results = []
+
+    for name, old_v, new_v in changed:
+        try:
+            owner, repo = find_github_repo(name)
+            cl = fetch_dep_changelog(owner, repo)
+            text, flagged = render_dep_diff(
+                cl, name, old_v, new_v, show_all=args.show_all
+            )
+            results.append({"package": name, "from": old_v, "to": new_v,
+                            "flagged": flagged, "text": text, "error": None})
+            total_flagged += flagged
+        except (ValueError, OSError) as e:
+            results.append({"package": name, "from": old_v, "to": new_v,
+                            "flagged": 0, "text": None, "error": str(e)})
+
+    if args.format == "json":
+        print(json.dumps(
+            {
+                "changed": [
+                    {k: v for k, v in r.items() if k != "text"}
+                    for r in results
+                ],
+                "added": added,
+                "removed": removed,
+                "flagged": total_flagged,
+            },
+            indent=2,
+        ))
+        return EXIT_FAIL if (args.strict and total_flagged) else EXIT_OK
+
+    if not changed and not added and not removed:
+        print("No pinned dependency changes found.")
+        return EXIT_OK
+    for r in results:
+        print()
+        if r["error"]:
+            print(f"{r['package']}: {r['from']} -> {r['to']}")
+            print(f"  (couldn't analyze: {r['error']})")
+        else:
+            print(r["text"])
+    if added:
+        print(f"\nNew dependencies: {', '.join(added)}")
+    if removed:
+        print(f"Removed dependencies: {', '.join(removed)}")
+    print(f"\nTotal: {len(changed)} version change(s), "
+          f"{total_flagged} breaking/security change(s) flagged.")
+    if args.strict and total_flagged:
+        return EXIT_FAIL
     return EXIT_OK
 
 

patchnotes/_depdiff.py

@@ -139,3 +139,42 @@ def render_dep_diff(
     else:
         lines.append("  No breaking or security changes flagged.")
     return "\n".join(lines), flagged
+
+
+# ── Requirements-file diffing ─────────────────────────────────────────────────
+
+_REQ_LINE = re.compile(
+    r'^\s*(?P<name>[A-Za-z0-9]([A-Za-z0-9._-]*[A-Za-z0-9])?)'
+    r'(?:\[[^\]]*\])?\s*==\s*(?P<version>[^\s;#]+)'
+)
+
+
+def parse_requirements(text: str) -> dict:
+    """Extract ``name==version`` pins from a requirements file.
+
+    Unpinned lines (>=, ~=, bare names, -r includes, URLs) are ignored —
+    version diffing only makes sense for exact pins.
+    """
+    pins: dict[str, str] = {}
+    for line in text.splitlines():
+        m = _REQ_LINE.match(line)
+        if m:
+            pins[m.group("name").lower()] = m.group("version")
+    return pins
+
+
+def diff_requirements(old_text: str, new_text: str) -> tuple:
+    """Compare two requirements files.
+
+    Returns (changed, added, removed) where changed is a list of
+    (name, old_version, new_version).
+    """
+    old, new = parse_requirements(old_text), parse_requirements(new_text)
+    changed = [
+        (name, old[name], new[name])
+        for name in sorted(old.keys() & new.keys())
+        if old[name] != new[name]
+    ]
+    added = sorted(new.keys() - old.keys())
+    removed = sorted(old.keys() - new.keys())
+    return changed, added, removed

patchnotes/_models.py

@@ -226,7 +226,9 @@ def _semantic_issues(self) -> list[ValidationIssue]:
                 )
             seen.add(r.version)
 
-            if not r.entries:
+            # An empty [Unreleased] section is normal (e.g. right after a
+            # release); only warn about empty *versioned* releases.
+            if not r.entries and not r.is_unreleased:
                 issues.append(
                     ValidationIssue(
                         _v.EMPTY_RELEASE,

patchnotes/_scaffold.py

@@ -0,0 +1,76 @@
+"""
+patchnotes._scaffold
+`patchnotes init` — starter changelog and CI workflow for new projects.
+"""
+
+from __future__ import annotations
+
+import os
+from typing import Optional
+
+STARTER_CHANGELOG = """\
+# Changelog
+
+All notable changes to this project are documented in this file. The format
+follows [Keep a Changelog](https://keepachangelog.com) and this project
+adheres to [Semantic Versioning](https://semver.org).
+
+## [Unreleased]
+
+### Added
+
+- Started tracking changes in this changelog
+"""
+
+STARTER_WORKFLOW = """\
+# Validates the changelog on every PR that touches it, with inline
+# annotations on offending lines. Generated by `patchnotes init --workflow`.
+name: Validate changelog
+
+on:
+  pull_request:
+    paths: ["{file}"]
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: Londopy/patchnotes@v2
+        with:
+          file: {file}
+          strict: "true"
+"""
+
+
+def starter_changelog(repo_url: Optional[str] = None) -> str:
+    """The starter CHANGELOG.md content (strict-validation clean)."""
+    text = STARTER_CHANGELOG
+    if repo_url:
+        text += f"\n[unreleased]: {repo_url.rstrip('/')}/commits\n"
+    return text
+
+
+def write_changelog(path: str, repo_url: Optional[str] = None) -> None:
+    """Create a starter changelog; refuses to overwrite."""
+    if os.path.exists(path):
+        raise FileExistsError(
+            f"{path} already exists — refusing to overwrite. "
+            f"Run `patchnotes {path} validate` to check it instead."
+        )
+    with open(path, "w", encoding="utf-8") as fh:
+        fh.write(starter_changelog(repo_url))
+
+
+def write_workflow(changelog_path: str) -> str:
+    """Create .github/workflows/changelog.yml next to the repo root."""
+    base = os.path.dirname(changelog_path) or "."
+    wf_dir = os.path.join(base, ".github", "workflows")
+    wf_path = os.path.join(wf_dir, "changelog.yml")
+    if os.path.exists(wf_path):
+        raise FileExistsError(f"{wf_path} already exists — refusing to overwrite.")
+    os.makedirs(wf_dir, exist_ok=True)
+    rel = os.path.basename(changelog_path)
+    with open(wf_path, "w", encoding="utf-8") as fh:
+        fh.write(STARTER_WORKFLOW.format(file=rel))
+    return wf_path