Tools: Add WIP Wednesday generation script

- Add Python3 script to generate WIP Wednesday articles in Markdown

Author: marcuspollio

tools/wip_wednesday.py

@@ -0,0 +1,390 @@
+import argparse
+import requests
+from collections import defaultdict
+from datetime import datetime, timedelta
+from email.utils import parsedate_to_datetime
+from pathlib import Path
+from typing import Any, DefaultDict
+
+
+GITHUB_REPO = "FreeCAD/FreeCAD"
+GITHUB_API = "https://api.github.com"
+
+WORKBENCH_ORDER = [
+    "Core", "Gui", "Part", "PartDesign", "Sketcher", "TechDraw", "Assembly",
+    "CAM", "Draft", "BIM", "FEM", "Measure", "Mesh", "Material", "Spreadsheet", "Surface"
+]
+
+
+def warn(text: str) -> str:
+    return f"\033[31m{text}\033[0m"
+
+
+def bold(text: str) -> str:
+    return f"\033[1;34m{text}\033[0m"
+
+
+def parse_time(timestr: str) -> datetime:
+    """
+    Parse time string in ISO 8601 (2026-01-01T01:23:45+00:00)
+    or RFC 2822 (Thu, 01 Jan 2026 01:23:45 GMT) format.
+    """
+    try:
+        dt = datetime.fromisoformat(timestr)
+    except ValueError:
+        try:
+            dt = parsedate_to_datetime(timestr)
+        except Exception:
+            raise SystemExit(f"{warn('⚠️ Error:')} Unsupported time format: {timestr}")
+
+    if dt.tzinfo is not None:
+        dt = dt.astimezone().replace(tzinfo=None)
+
+    return dt
+
+
+def is_wednesday(dt: datetime) -> bool:
+    return dt.weekday() == 2  # Monday=0, Wednesday=2
+
+
+def previous_wednesday(dt: datetime, set_time: tuple[int, int, int] | None = None) -> datetime:
+    """Return the most recent Wednesday with optional time (hour, minute, second)."""
+    days_back = (dt.weekday() - 2) % 7
+    new_dt = dt - timedelta(days=days_back)
+    if set_time is not None:
+        hour, minute, second = set_time
+        new_dt = new_dt.replace(hour=hour, minute=minute, second=second, microsecond=0)
+    return new_dt
+
+
+def format_dt(dt: datetime) -> str:
+    return dt.strftime("%A, %d %B %Y %H:%M:%S")
+
+
+def info(message: str, dt: datetime) -> None:
+    """Print labeled datetime in bold."""
+    print(f"→ {message}: {bold(format_dt(dt))}")
+
+
+def prompt_user_for_date(dt: datetime) -> datetime:
+    new_dt = previous_wednesday(dt, set_time=(12, 0, 0))  # suggest Wednesday at 12:00 UTC
+
+    print(f"\n{warn('⚠️ Warning:')} The selected time is not a Wednesday.")
+    info("Selected time", dt)
+    print(f"How to proceed?")
+    print(f"  [Enter/Y] Continue with selected time")
+    print(f"  [W]       Pick most recent Wednesday: {format_dt(new_dt)}")
+
+    try:
+        choice = input("> ").strip().lower()
+    except EOFError:
+        print(f"\n{warn('⚠️ Warning:')} No input available.")
+        info("Continuing with", dt)
+        return dt
+
+    if choice in ("", "y", "yes"):
+        info("Continuing with", dt)
+        return dt
+    elif choice == "w":
+        info("Continuing with most recent Wednesday", new_dt)
+        return new_dt
+    else:
+        print(f"\n{warn('⚠️ Warning:')} Invalid choice, defaulting to selected time.")
+        info("Continuing with", dt)
+        return dt
+
+
+def build_output_path(base_dir: Path, dt: datetime) -> Path:
+    slug = dt.strftime("wip-wednesday-%d-%B-%Y").lower()
+
+    return base_dir / "content" / "en" / "news" / dt.strftime("%Y/%m") / slug / "index.md"
+
+
+def generate_front_matter(dt: datetime, author: str) -> str:
+    return f"""---
+title: WIP Wednesday - {dt.strftime("%d %B %Y")}
+date: {dt.strftime("%Y-%m-%d")}
+authors: {author}
+draft: false
+categories: update
+tags:
+- WIP
+cover:
+  image:
+  caption:
+---
+"""
+
+
+def github_get(url: str, headers: dict[str, str], params: dict[str, Any]) -> requests.Response:
+    r = requests.get(url, headers=headers, params=params)
+    r.raise_for_status()
+    return r
+
+
+def extract_page(link_header: str) -> int | None:
+    if not link_header:
+        return None
+    try:
+        part = link_header.split(",")[0]
+        return int(part.split("page=")[-1].split(">")[0])
+    except Exception:
+        return None
+
+
+def fetch_github_data(dt: datetime, token: str | None = None) -> tuple[list[dict[str, Any]], int, int]:
+    """
+    Fetch FreeCAD PR and issue data for the week ending at dt (12:00 UTC Wednesday).
+    Returns:
+        merged_prs: list of merged PRs in the week
+        open_prs_count: number of currently open PRs
+        open_issues_count: number of currently open issues
+    """
+    until = dt
+    since = dt - timedelta(days=7)
+
+    search_url = f"{GITHUB_API}/search/issues"
+    headers = {"Accept": "application/vnd.github.v3+json"}
+    if token:
+        headers["Authorization"] = f"token {token}"
+
+    merged_prs = []
+
+    page = 1
+    while True:
+        params = {
+            "q": f"repo:{GITHUB_REPO} is:pr is:merged merged:{since.isoformat()}..{until.isoformat()}",
+            "sort": "updated",
+            "order": "desc",
+            "per_page": 100,
+            "page": page,
+        }
+        r = github_get(search_url, headers, params)
+        items = r.json().get("items", [])
+        if not items:
+            break
+        merged_prs.extend(items)
+        if "next" not in r.links:
+            break
+        page += 1
+
+    search_prs_url = f"{GITHUB_API}/repos/{GITHUB_REPO}/pulls"
+    prs_params = {
+        "state": "open",
+        "per_page": 1
+    }
+    r_open_prs = github_get(search_prs_url, headers, prs_params)
+    last_page = extract_page(r_open_prs.headers.get("Link", ""))
+    open_prs_count = last_page if last_page is not None else len(r_open_prs.json())
+
+    issues_params = {
+        "q": f"repo:{GITHUB_REPO} is:issue is:open",
+        "per_page": 1,
+    }
+    r_open_issues = github_get(search_url, headers, issues_params)
+    open_issues_count = r_open_issues.json().get("total_count", 0)
+
+    return merged_prs, open_prs_count, open_issues_count
+
+
+def get_pr_type(pr: dict) -> str:
+    """
+    Classify PR into backport, feature, fix, other.
+    Uses labels first then falls back to title heuristics.
+    """
+    labels = [label["name"].lower() for label in pr.get("labels", [])]
+    title = pr.get("title", "").lower()
+
+    if "backport" in title:
+        return "backport"
+
+    if any(l in ("feature", "enhancement") for l in labels) \
+       or any(k in title for k in ["add", "feature", "implement", "support", "enable", "improve", "introduce"]):
+        return "feature"
+
+    if any(l in ("bug", "bugfix", "fix") for l in labels) \
+       or any(k in title for k in ["fix", "bug", "crash", "error", "resolve", "regression", "correct"]):
+        return "fix"
+
+    return "other"
+
+
+def get_pr_type_stats(prs: list[dict[str, Any]]) -> dict[str, int]:
+    stats = {
+        "total": len(prs),
+        "backport": 0,
+        "feature": 0,
+        "fix": 0,
+        "other": 0,
+    }
+
+    for pr in prs:
+        pr_type = get_pr_type(pr)
+        stats[pr_type] += 1
+
+    return stats
+
+
+def get_pr_commit_authors(pr_number: int, headers: dict[str, str]) -> set[str]:
+    url = f"{GITHUB_API}/repos/{GITHUB_REPO}/pulls/{pr_number}/commits"
+    authors = set()
+
+    page = 1
+    while True:
+        params = {"per_page": 100, "page": page}
+        r = github_get(url, headers, params)
+        commits = r.json()
+        if not commits:
+            break
+
+        for c in commits:
+            author = c.get("author")
+            if author and author.get("login"):
+                authors.add(author["login"])
+            else:
+                commit_author = c.get("commit", {}).get("author", {})
+                name = commit_author.get("name")
+                if name:
+                    authors.add(name)
+
+        if "next" not in r.links:
+            break
+        page += 1
+
+    return authors
+
+
+def class_prs(prs: list[dict[str, Any]], headers: dict[str, str]) -> tuple[
+    DefaultDict[str, list[tuple[str, str, int, str]]],
+    list[tuple[str, str, int, str]]
+]:
+    """Return workbench and other changes dictionaries."""
+    workbench_changes = defaultdict(list)
+    other_changes = []
+
+    for pr in prs:
+        labels = [label["name"] for label in pr.get("labels", [])]
+        title = pr.get("title", "")
+        title_lower = title.lower()
+        number = pr.get("number")
+        url = pr.get("html_url")
+        authors = get_pr_commit_authors(number, headers)
+        authors.discard("pre-commit-ci[bot]")
+        author_str = ", ".join(sorted(authors)) if authors else "unknown"
+
+        assigned = False
+        for wb in WORKBENCH_ORDER:
+            if wb.lower() in title_lower or any(wb.lower() in label.lower() for label in labels):
+                workbench_changes[wb].append((author_str, title, number, url))
+                assigned = True
+                break
+        if not assigned:
+            other_changes.append((author_str, title, number, url))
+
+    return workbench_changes, other_changes
+
+
+def generate_body(
+    dt: datetime,
+    workbench_changes: dict[str, list[tuple[str, str]]],
+    other_changes: list[tuple[str, str]],
+    contributors: list[str],
+    pr_stats: dict[str, int],
+    issue_stats: dict[str, int],
+    pr_type_stats: dict[str, int],
+) -> str:
+
+    lines = ["This week in FreeCAD development:\n"]
+    lines.append(f"- Total PRs merged: {pr_type_stats['total']}")
+    lines.append(f"- Backport PRs: {pr_type_stats['backport']}")
+    lines.append(f"- Feature PRs: {pr_type_stats['feature']}")
+    lines.append(f"- Fix PRs: {pr_type_stats['fix']}")
+    lines.append(f"- Other PRs: {pr_type_stats['other']}\n")
+
+    for wb in WORKBENCH_ORDER:
+        prs = workbench_changes.get(wb)
+        if prs:
+            lines.append(f"### {wb}:")
+            for user, title, number, url in prs:
+                lines.append(f"  - {user} | {title} [#{number}]({url})")
+            lines.append("")
+
+    if other_changes:
+        lines.append("### Other changes:")
+        for user, title, number, url in other_changes:
+            lines.append(f"  - {user} {title} [#{number}]({url})")
+        lines.append("")
+
+    if contributors:
+        lines.append(f"Additional improvements and fixes were contributed by {', '.join(contributors)}.\n")
+
+    lines.append(
+        f"If you are interested in testing you can grab [the latest weekly build]"
+        f"(https://github.com/{GITHUB_REPO}/releases/tag/weekly-{dt.strftime('%Y.%m.%d')}).\n")
+
+    lines.append(
+        f"PR stats: since the previous report, {pr_stats['merged']} pull requests have been merged, "
+        f"and {pr_stats['opened']} new pull requests have been opened.\n")
+    lines.append(
+        f"Issue stats: overall, there are {issue_stats['open']} open issues in the tracker, "
+        f"up/down by {issue_stats['delta']} from last week.\n")
+
+    return "\n".join(lines)
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Generate Hugo WIP Wednesday markdown.")
+    parser.add_argument("--time", help="Optional timestamp (ISO 8601 or RFC 2822)")
+    parser.add_argument("--author", help="Optional Author name", default="")
+    parser.add_argument("--root", type=Path, default=Path.cwd())
+    parser.add_argument("--ci", action="store_true", help="Skip prompts")
+    parser.add_argument("--token", help="GitHub token to increase API limits", default=None)
+    args = parser.parse_args()
+
+    dt = parse_time(args.time) if args.time else datetime.now().astimezone().replace(tzinfo=None)
+
+    if is_wednesday(dt):
+        dt = dt.replace(hour=12, minute=0, second=0, microsecond=0)
+        info("Using Wednesday", dt)
+    elif args.ci:
+        dt = previous_wednesday(dt, set_time=(12, 0, 0))
+        info("Using most recent Wednesday (CI)", dt)
+    else:
+        dt = prompt_user_for_date(dt)
+
+    out_path = build_output_path(args.root, dt)
+
+    if out_path.exists():
+        raise SystemExit(f"{warn('⚠️ Error:')} File exists: {bold(out_path)}")
+
+    out_path.parent.mkdir(parents=True, exist_ok=True)
+
+    headers = {"Accept": "application/vnd.github.v3+json"}
+    if args.token:
+        headers["Authorization"] = f"token {args.token}"
+
+    merged_prs, open_prs_count, open_issues_count = fetch_github_data(dt, token=args.token)
+    pr_type_stats = get_pr_type_stats(merged_prs)
+    workbench_changes, other_changes = class_prs(merged_prs, headers)
+    contributors = sorted({
+        pr.get("user", {}).get("login", "unknown")
+        for pr in merged_prs
+        if pr.get("user")
+    })
+
+    pr_stats = {
+        "merged": len(merged_prs),
+        "opened": open_prs_count,
+    }
+
+    issue_stats = {"open": open_issues_count, "delta": 0}
+    front_matter = generate_front_matter(dt, args.author)
+    body = generate_body(dt, workbench_changes, other_changes, contributors, pr_stats, issue_stats, pr_type_stats)
+
+    out_path.write_text(front_matter + "\n" + body + "\n", encoding="utf-8")
+
+    print(f"Created: {bold(out_path)}")
+
+
+if __name__ == "__main__":
+    main()