mkdocs2confluence 0.13.6__tar.gz → 0.13.7__tar.gz

{mkdocs2confluence-0.13.6/src/mkdocs2confluence.egg-info → mkdocs2confluence-0.13.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mkdocs2confluence
-Version: 0.13.6
+Version: 0.13.7
 Summary: Publish MkDocs Material pages to Confluence Cloud — admonitions, Mermaid diagrams, tabs, page properties and more
 Author: Anders Hybertz
 License: GPL-3.0-or-later

{mkdocs2confluence-0.13.6 → mkdocs2confluence-0.13.7}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "mkdocs2confluence"
-version = "0.13.6"
+version = "0.13.7"
 description = "Publish MkDocs Material pages to Confluence Cloud — admonitions, Mermaid diagrams, tabs, page properties and more"
 readme = "README.md"
 license = { text = "GPL-3.0-or-later" }

{mkdocs2confluence-0.13.6 → mkdocs2confluence-0.13.7/src/mkdocs2confluence.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mkdocs2confluence
-Version: 0.13.6
+Version: 0.13.7
 Summary: Publish MkDocs Material pages to Confluence Cloud — admonitions, Mermaid diagrams, tabs, page properties and more
 Author: Anders Hybertz
 License: GPL-3.0-or-later

{mkdocs2confluence-0.13.6 → mkdocs2confluence-0.13.7}/src/mkdocs_to_confluence/skills/mkdocs-changelog/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: mkdocs-changelog
 description: Analyse doc changes since the last CHANGELOG.md update and draft a major-change entry if the changes qualify.
-version: "1.2.0"
+version: "1.3.0"
 tags: [documentation, git, changelog, mkdocs, confluence]
 specificity: context-specific
 tool_agnostic: true
@@ -22,15 +22,24 @@ Analyse git changes to the docs directory since the last `CHANGELOG.md` commit.
 
 1. **Extract git data** — run the bundled data script to get structured, deterministic input:
 
+   Normal update (since last CHANGELOG.md commit):
    ```
    python .mk2conf/scripts/changelog_data.py --docs-dir <docs_dir>
    ```
 
+   Initial changelog (from a specific date):
+   ```
+   python .mk2conf/scripts/changelog_data.py --docs-dir <docs_dir> --since YYYY-MM-DD
+   ```
+
    The script prints a JSON object to stdout. Use this as your sole source of truth for
    commits, changed files, and contributors. Do not run git commands yourself.
 
    If the script is missing, tell the user to run `mk2conf install-skill` first.
 
+   When `--since` is used, the JSON will contain `"mode": "since_date"`. Use this to
+   trigger the initial changelog flow described below.
+
 2. **Read the existing changelog** — read `<docs_dir>/CHANGELOG.md` for context on what
    was previously recorded.
 
@@ -109,6 +118,26 @@ All notable changes to this documentation are recorded here.
 The format is inspired by [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 ```
 
+## Initial changelog (--since DATE)
+
+When the script is run with `--since` and the JSON contains `"mode": "since_date"`,
+the user wants to bootstrap a CHANGELOG.md from scratch for a given time window.
+
+Different rules apply:
+
+- **Always draft** — the MAJOR threshold does not apply. This is a retrospective
+  summary, not an incremental gate.
+- **Group by theme**, not by individual commit. Synthesise the changed files and
+  commit subjects into meaningful categories.
+- **Date range in the title** — use the `since` value from the JSON as the start
+  and `date` as the end, e.g. `2026-05-01 → 2026-05-27`.
+- **If CHANGELOG.md already exists**, stop and ask the user whether they want to
+  prepend, append, or replace. Do not overwrite silently.
+- **If CHANGELOG.md does not exist**, create it with the standard header and the
+  entry as `???+`.
+
+Example title: `2026-05-01 → 2026-05-27 — Initial documentation release`
+
 ## Pitfalls
 
 - **Do not draft an entry for every change.** The changelog is for readers who want to know

{mkdocs2confluence-0.13.6 → mkdocs2confluence-0.13.7}/src/mkdocs_to_confluence/skills/mkdocs-changelog/scripts/changelog_data.py

@@ -37,6 +37,16 @@ def _baseline_commit(changelog_path: str) -> str | None:
     return sha or None
 
 
+def _commit_before_date(since_date: str) -> str | None:
+    """Return the SHA of the last commit strictly before since_date (YYYY-MM-DD), or None."""
+    sha = _run([
+        "git", "log", "--format=%H",
+        f"--before={since_date}",
+        "-1",
+    ])
+    return sha or None
+
+
 def _root_commit() -> str:
     """Return the SHA of the very first commit in the repo."""
     return _run(["git", "rev-list", "--max-parents=0", "HEAD"])
@@ -102,19 +112,39 @@ def main() -> None:
         default="docs",
         help="Path to the MkDocs docs directory, relative to project root (default: docs)",
     )
+    parser.add_argument(
+        "--since",
+        metavar="DATE",
+        default=None,
+        help=(
+            "Use the last commit before DATE (YYYY-MM-DD) as the baseline instead of the "
+            "last commit that touched CHANGELOG.md. Useful for creating an initial changelog."
+        ),
+    )
     args = parser.parse_args()
 
     docs_dir: str = args.docs_dir
     changelog_rel = f"{docs_dir}/CHANGELOG.md"
 
-    # Baseline: last commit touching CHANGELOG.md, or root commit if none
-    baseline = _baseline_commit(changelog_rel) or _root_commit()
-    if not baseline:
-        print(
-            "error: could not determine a baseline commit — is this a git repository?",
-            file=sys.stderr,
-        )
-        sys.exit(1)
+    # Baseline resolution — --since takes priority
+    if args.since:
+        baseline = _commit_before_date(args.since)
+        if not baseline:
+            print(
+                f"error: no commit found before {args.since}",
+                file=sys.stderr,
+            )
+            sys.exit(1)
+        mode = "since_date"
+    else:
+        baseline = _baseline_commit(changelog_rel) or _root_commit()
+        if not baseline:
+            print(
+                "error: could not determine a baseline commit — is this a git repository?",
+                file=sys.stderr,
+            )
+            sys.exit(1)
+        mode = "changelog_commit"
 
     commits = _commits_since(baseline)
     changes = _changed_files(baseline, docs_dir)
@@ -122,6 +152,8 @@ def main() -> None:
 
     output = {
         "date": date.today().isoformat(),
+        "mode": mode,
+        "since": args.since,
         "baseline_commit": baseline,
         "commits": commits,
         "contributors": contributors,