git-to-doc 0.2.1__tar.gz → 0.2.2__tar.gz

{git_to_doc-0.2.1 → git_to_doc-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: git-to-doc
-Version: 0.2.1
+Version: 0.2.2
 Summary: Conventional Commit messages, changelogs & PRs from git diffs using Gemma (local or cloud)
 Requires-Python: >=3.9
 Description-Content-Type: text/markdown

{git_to_doc-0.2.1 → git_to_doc-0.2.2}/git_to_doc/evaluate.py

@@ -14,17 +14,16 @@ from git_to_doc.model import _client, _resolve_model
 DEFAULT_JUDGE = "gpt-oss:120b"
 
 RUBRIC = [
-    ("format_compliance", 0.20,
-     "Commit header matches Conventional Commits, valid type, imperative, "
-     "no trailing period, <= 72 chars. 5 = perfect, 1 = not conventional."),
-    ("type_accuracy", 0.15,
-     "type/scope correctly reflect the change. 5 = right, 1 = wrong."),
-    ("semantic_accuracy", 0.30,
+    ("conventional_commit", 0.15,
+     "Commit header matches Conventional Commits, valid type/scope, imperative mood. 5 = perfect, 1 = invalid."),
+    ("semantic_accuracy", 0.25,
      "Truthfully describes the diff, no hallucination/omission. 5 = faithful, 1 = fabricated."),
-    ("conciseness", 0.15,
-     "Terse, free of filler/preamble. 5 = clean, 1 = bloated."),
-    ("changelog_quality", 0.20,
-     "Valid markdown, user-facing, accurate. 5 = useful, 1 = missing/wrong."),
+    ("changelog_quality", 0.15,
+     "Valid markdown, user-facing, accurate changelog entry. 5 = useful, 1 = missing/wrong."),
+    ("plain_english_quality", 0.25,
+     "The 'What changed' section explains the change clearly to a human reader, and file notes accurately summarize file changes. 5 = excellent, 1 = confusing/absent."),
+    ("reviewer_utility", 0.20,
+     "The review notes highlight tricky parts, design decisions, and are highly actionable for reviewers. 5 = highly useful, 1 = generic/empty."),
 ]
 
 

{git_to_doc-0.2.1 → git_to_doc-0.2.2}/git_to_doc/model.py

@@ -84,24 +84,22 @@ class CommitDoc(BaseModel):
 
 
 SYSTEM_PROMPT = """
-
 You are a senior developer and expert technical writer.
 Given a raw git diff, output ONLY a valid JSON object with no explanation, no markdown fences, no preamble.
 
 Rules for each field:
 - type: one of feat|fix|docs|refactor|perf|test|chore|ci|build|revert
 - scope: lowercase name of the module or folder most affected (null if unclear)
-- subject: imperative mood, lowercase, no trailing period, max 72 chars. Make it read naturally like a human wrote it.
-- body: 1-3 sentences of technical detail (null if simple). Be descriptive but concise.
+- subject: imperative mood, lowercase, no trailing period, max 72 chars. Write it like a human developer would — natural and specific, not robotic.
+- body: 2-4 sentences of precise technical detail explaining WHAT was changed and WHY. Reference specific function names, file paths, or patterns you see in the diff. Never be vague. null if truly trivial.
 - breaking: true ONLY if existing public API contracts are removed or changed incompatibly
-- changelog_entry: a detailed markdown bullet like "- feat(scope): humanized description" ready for CHANGELOG.md. Make it user-focused.
-- plain_english: 1-2 sentences a non-technical person could understand explaining WHAT changed and WHY.
-- human_title: A highly understandable, plain English title for the document (e.g. "New Feature: Added user authentication" or "Bug Fix: Resolved crash on startup").
-- review_notes: 1-2 paragraphs highlighting tricky parts, design decisions, or areas reviewers should focus on.
-- file_notes: A dictionary mapping the most important changed file paths to a 1-sentence summary of what changed in that file. (e.g. {"src/main.py": "Added initialization logic for the new auth flow."})
+- changelog_entry: a user-facing markdown bullet starting with "- " that summarizes the change for a CHANGELOG.md. Be specific and helpful — mention the feature, fix, or improvement by name. For large changes, use multiple sub-bullets with "  - " to break down the key items.
+- plain_english: 3-5 sentences explaining this change to a developer who hasn't seen the code. Cover: (1) what the code did before, (2) what it does now, and (3) why this matters. Use concrete language, not vague summaries. Reference module names and behaviors.
+- human_title: A clear, specific title for the document. Bad: "Code Update". Good: "Refactor: Simplified checkpoint loading to return checkpointer objects directly". The title should tell someone exactly what happened without opening the doc.
+- review_notes: 2-3 paragraphs for code reviewers. Paragraph 1: the overall approach and key design decisions. Paragraph 2: specific areas that need careful review (e.g., edge cases, error handling, concurrency). Paragraph 3 (optional): suggestions for follow-up work or things that were intentionally left out.
+- file_notes: A dictionary mapping up to 10 of the MOST IMPORTANT changed file paths to a 1-sentence summary of what changed in each. Focus on files where the logic actually changed, not config or boilerplate. If the diff has more than 10 files, pick the ones with the most substantive changes.
 
 Output format: raw JSON only. No ```json fences. No commentary.
-
 """
 
 

{git_to_doc-0.2.1 → git_to_doc-0.2.2}/git_to_doc/renderer.py

@@ -170,23 +170,41 @@ def render_markdown_file(doc: CommitDoc, model: str = "gemma4",
     section = _SECTION.get(doc.type, "Changed")
     changelog_block = f"### {section}\n{doc.changelog_entry}"
 
+    # 5. Files section — key files with notes shown prominently, rest collapsed
     files_section = ""
     if stats and stats.get("files"):
-        file_lines = []
+        noted_lines = []
+        other_lines = []
         for f in stats["files"]:
             note = doc.file_notes.get(f)
             if note:
-                file_lines.append(f"- `{f}` — {note}")
+                noted_lines.append(f"| `{f}` | {note} |")
             else:
-                file_lines.append(f"- `{f}`")
-        files_list = "\n".join(file_lines)
-        files_section = (f"<details>\n<summary>Files changed ({n_files})</summary>\n\n"
-                         f"{files_list}\n\n</details>\n\n")
-
+                other_lines.append(f"- `{f}`")
+
+        parts = []
+        if noted_lines:
+            parts.append("### Key files\n")
+            parts.append("| File | Change |")
+            parts.append("|------|--------|")
+            parts.extend(noted_lines)
+            parts.append("")
+
+        if other_lines:
+            other_text = "\n".join(other_lines)
+            parts.append(f"<details>\n<summary>Other files changed ({len(other_lines)})</summary>\n")
+            parts.append(other_text)
+            parts.append("\n</details>\n")
+
+        if parts:
+            files_section = "\n".join(parts) + "\n"
+
+    # 6. Review notes
     review_section = ""
     if doc.review_notes:
-        review_section = f"## Review Notes\n\n{doc.review_notes}\n\n"
+        review_section = f"## Review notes\n\n{doc.review_notes}\n\n"
 
+    # 7. Metadata (always collapsed)
     src_row = f"| Source | {source} |\n" if source else ""
     meta_section = (f"<details>\n<summary>Metadata</summary>\n\n"
                     f"| Field | Value |\n|-------|-------|\n"
@@ -208,7 +226,7 @@ def render_markdown_file(doc: CommitDoc, model: str = "gemma4",
 
 {doc.plain_english}
 
-## Commit message
+{review_section}## Commit message
 
 ```
 {commit_block}
@@ -220,5 +238,7 @@ def render_markdown_file(doc: CommitDoc, model: str = "gemma4",
 {changelog_block}
 ```
 
-{review_section}{files_section}{meta_section}"""
+## Files
+
+{files_section}{meta_section}"""
 

{git_to_doc-0.2.1 → git_to_doc-0.2.2}/git_to_doc.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: git-to-doc
-Version: 0.2.1
+Version: 0.2.2
 Summary: Conventional Commit messages, changelogs & PRs from git diffs using Gemma (local or cloud)
 Requires-Python: >=3.9
 Description-Content-Type: text/markdown

{git_to_doc-0.2.1 → git_to_doc-0.2.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "git-to-doc"
-version = "0.2.1"
+version = "0.2.2"
 description = "Conventional Commit messages, changelogs & PRs from git diffs using Gemma (local or cloud)"
 readme = "README.md"
 requires-python = ">=3.9"