You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@community.apache.org by rb...@apache.org on 2026/03/30 13:30:55 UTC

(comdev) 02/03: Initial import

This is an automated email from the ASF dual-hosted git repository.

rbowen pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/comdev.git

commit 3022587d96e81ad39c145f4de63f0d8766a5c567
Author: Rich Bowen <rb...@rcbowen.com>
AuthorDate: Fri Mar 13 10:46:38 2026 +0000

    Initial import
---
 README.md                            |  19 ++-
 asf-highlights/README.md             |  28 +++
 asf-highlights/asf_activity.py       | 158 +++++++++++++++++
 asf-highlights/project_birthdays.py  | 204 ++++++++++++++++++++++
 project-activity/README.md           |  54 ++++++
 project-activity/project_activity.py | 322 +++++++++++++++++++++++++++++++++++
 6 files changed, 783 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index 38e9d9f..5fee5d5 100644
--- a/README.md
+++ b/README.md
@@ -1,2 +1,17 @@
-# comdev
-ASF Comdev tools
+# ASF Comdev tools
+
+ASF Community Development (ComDev) project partners with other groups across the ASF to provide resources, tools, programs, and advice in order to attract, retain, educate, and grow key communities around the Apache Software Foundation, in support of sustainability producing software for the public good.
+
+Other repositories:
+
+* [comdev-site](https://github.com/apache/comdev-site)
+* [comdev-working-groups](https://github.com/apache/comdev-working-groups)
+* [comdev-projects](https://github.com/apache/comdev-projects)
+* [comdev-events-site](https://github.com/apache/comdev-events-site)
+* [comdev-reporter](https://github.com/apache/comdev-reporter)
+
+Contents of this repository:
+
+* asf-highlights - tools for finding foundation-wide activity
+* project-activities - tools for project-specific activity
+
diff --git a/asf-highlights/README.md b/asf-highlights/README.md
new file mode 100644
index 0000000..cc8831a
--- /dev/null
+++ b/asf-highlights/README.md
@@ -0,0 +1,28 @@
+# ASF Highlights
+
+Scripts for generating monthly summaries of Apache Software Foundation activity. Both scripts use [uv](https://docs.astral.sh/uv/) for dependency management and can be run directly.
+
+## asf_activity.py
+
+Reports on ASF activity from the previous month: new committers, new PMC members, and software releases.
+
+```
+./asf_activity.py [OPTIONS]
+```
+
+Options:
+- `committers` — New committers added last month
+- `pmc` — New PMC members added last month
+- `releases` — Releases made last month
+- `all` — All of the above (default)
+- `-h`, `--help` — Show help
+
+Multiple options can be combined, e.g. `uv run asf_activity.py committers pmc`.
+
+## project_birthdays.py
+
+Generates a Markdown summary of Apache projects celebrating their establishment anniversary in the current month. Output (summary and log file) is written to the `birthdays/` directory.
+
+```
+./project_birthdays.py
+```
diff --git a/asf-highlights/asf_activity.py b/asf-highlights/asf_activity.py
new file mode 100755
index 0000000..7408e14
--- /dev/null
+++ b/asf-highlights/asf_activity.py
@@ -0,0 +1,158 @@
+#!/usr/bin/env -S uv run --script
+# /// script
+# dependencies = ["httpx"]
+# ///
+
+import httpx
+import sys
+from datetime import datetime, timedelta
+from collections import defaultdict
+
+def get_date_range():
+    today = datetime.now()
+    last_month_start = (today.replace(day=1) - timedelta(days=1)).replace(day=1)
+    last_month_end = today.replace(day=1) - timedelta(days=1)
+    return last_month_start, last_month_end
+
+def find_committers():
+    people_data = httpx.get("https://projects.apache.org/json/foundation/people.json").json()
+    ldap_data = httpx.get("https://whimsy.apache.org/public/public_ldap_people.json").json()
+    
+    last_month_start, last_month_end = get_date_range()
+    new_committers = defaultdict(list)
+    
+    for person_id, person_info in people_data.items():
+        if person_id not in ldap_data["people"]:
+            continue
+        
+        created = datetime.strptime(ldap_data["people"][person_id]["createTimestamp"], "%Y%m%d%H%M%SZ")
+        
+        if last_month_start <= created <= last_month_end:
+            for group in person_info.get("groups", []):
+                if not group.endswith("-pmc") and group not in ["apldap", "incubator"]:
+                    new_committers[group].append({
+                        "name": person_info.get("name", person_id),
+                        "id": person_id,
+                        "date": created.strftime("%Y-%m-%d")
+                    })
+    
+    if new_committers:
+        total = sum(len(c) for c in new_committers.values())
+        print(f"In {last_month_start.strftime('%B, %Y')}, {len(new_committers)} projects added a total of {total} new committers\n")
+        for project in sorted(new_committers.keys()):
+            print(f"{project.upper()}:")
+            for committer in new_committers[project]:
+                print(f"  - {committer['name']} ({committer['id']}) on {committer['date']}")
+            print()
+    else:
+        print(f"No new committers added in {last_month_start.strftime('%B %Y')}")
+
+def find_pmc():
+    committee_data = httpx.get("https://whimsy.apache.org/public/committee-info.json").json()
+    committees_data = httpx.get("https://projects.apache.org/json/foundation/committees.json").json()
+    
+    last_month_start, last_month_end = get_date_range()
+    reporting_month = last_month_start.strftime("%Y-%m")
+    new_pmc_members = defaultdict(list)
+    new_projects = set()
+    
+    # Identify projects established in the reporting month
+    for committee in committees_data:
+        if committee.get("established") == reporting_month:
+            new_projects.add(committee.get("id", "").lower())
+    
+    for project_id, project_info in committee_data.get("committees", {}).items():
+        if not project_info.get("pmc"):
+            continue
+        
+        for member_id, member_info in project_info.get("roster", {}).items():
+            date_str = member_info.get("date")
+            if not date_str:
+                continue
+            
+            added = datetime.strptime(date_str, "%Y-%m-%d")
+            
+            if last_month_start <= added <= last_month_end:
+                new_pmc_members[project_id].append({
+                    "name": member_info.get("name", member_id),
+                    "id": member_id,
+                    "date": date_str
+                })
+    
+    if new_pmc_members:
+        total = sum(len(m) for m in new_pmc_members.values())
+        new_project_members = sum(len(m) for p, m in new_pmc_members.items() if p in new_projects)
+        
+        summary = f"In {last_month_start.strftime('%B, %Y')}, {len(new_pmc_members)} projects added a total of {total} new PMC members"
+        if new_project_members > 0:
+            summary += f". {new_project_members} of those are part of newly-established projects"
+        print(summary + "\n")
+        
+        for project in sorted(new_pmc_members.keys()):
+            project_label = f"{project.upper()}"
+            if project in new_projects:
+                project_label += " 🎉 (New Project)"
+            print(f"{project_label}:")
+            for member in new_pmc_members[project]:
+                print(f"  - {member['name']} ({member['id']}) on {member['date']}")
+            print()
+    else:
+        print(f"No new PMC members added in {last_month_start.strftime('%B %Y')}")
+
+def find_releases():
+    releases_data = httpx.get("https://projects.apache.org/json/foundation/releases.json").json()
+    
+    last_month_start, last_month_end = get_date_range()
+    project_releases = defaultdict(list)
+    
+    for project_id, releases in releases_data.items():
+        for release_name, release_date_str in releases.items():
+            release_date = datetime.strptime(release_date_str, "%Y-%m-%d")
+            
+            if last_month_start <= release_date <= last_month_end:
+                project_releases[project_id].append({
+                    "name": release_name,
+                    "date": release_date_str
+                })
+    
+    if project_releases:
+        total = sum(len(r) for r in project_releases.values())
+        print(f"In {last_month_start.strftime('%B, %Y')}, {len(project_releases)} projects made {total} releases\n")
+        for project in sorted(project_releases.keys()):
+            print(f"{project.upper()}:")
+            for release in project_releases[project]:
+                print(f"  - {release['name']} on {release['date']}")
+            print()
+    else:
+        print(f"No releases made in {last_month_start.strftime('%B %Y')}")
+
+if __name__ == "__main__":
+    args = sys.argv[1:]
+    
+    if "-h" in args or "--help" in args:
+        print("Usage: find_activity.py [OPTIONS]")
+        print("\nOptions:")
+        print("  committers    Show new committers added last month")
+        print("  pmc           Show new PMC members added last month")
+        print("  releases      Show releases made last month")
+        print("  all           Show all reports (default)")
+        print("  -h, --help    Show this help message")
+        print("\nExamples:")
+        print("  find_activity.py")
+        print("  find_activity.py committers")
+        print("  find_activity.py pmc releases")
+        sys.exit(0)
+    
+    if not args or "all" in args:
+        find_committers()
+        print("\n" + "="*80 + "\n")
+        find_pmc()
+        print("\n" + "="*80 + "\n")
+        find_releases()
+    else:
+        if "committers" in args:
+            find_committers()
+        if "pmc" in args:
+            find_pmc()
+        if "releases" in args:
+            find_releases()
diff --git a/asf-highlights/project_birthdays.py b/asf-highlights/project_birthdays.py
new file mode 100755
index 0000000..85a6b4a
--- /dev/null
+++ b/asf-highlights/project_birthdays.py
@@ -0,0 +1,204 @@
+#!/usr/bin/env -S uv run
+# /// script
+# requires-python = ">=3.8"
+# dependencies = [
+#     "requests",
+# ]
+# ///
+"""
+Apache Project Birthday Tracker - A script to generate monthly summaries of Apache project birthdays
+"""
+
+import os
+import sys
+import json
+import logging
+import requests
+from datetime import datetime, timedelta
+from pathlib import Path
+from collections import defaultdict
+
+# Configuration
+CONFIG = {
+    "committees_url": "https://projects.apache.org/json/foundation/committees.json",
+    "output_dir": "birthdays",
+    "current_month": datetime.now().month,  # Default to current month
+    "current_year": datetime.now().year     # Default to current year
+}
+
+def ensure_output_dir():
+    """Create the output directory if it doesn't exist"""
+    output_path = Path(CONFIG["output_dir"])
+    output_path.mkdir(parents=True, exist_ok=True)
+    return output_path
+
+# Configure logging (after ensuring output directory exists)
+ensure_output_dir()
+logging.basicConfig(
+    level=logging.INFO,
+    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s',
+    handlers=[
+        logging.FileHandler(Path(CONFIG["output_dir"]) / "project_birthdays.log"),
+        logging.StreamHandler(sys.stdout)
+    ]
+)
+logger = logging.getLogger("apache_birthdays_tracker")
+
+def fetch_json_data(url):
+    """Fetch JSON data from a URL"""
+    logger.info(f"Fetching data from {url}")
+    try:
+        response = requests.get(url, timeout=30)
+        response.raise_for_status()
+        return response.json()
+    except requests.exceptions.RequestException as e:
+        logger.error(f"Error fetching data from {url}: {e}")
+        return None
+
+def get_month_name(month_number):
+    """Convert month number to month name"""
+    return datetime(2000, month_number, 1).strftime('%B')
+
+def get_projects_with_birthdays(committees_data, month):
+    """
+    Find projects with birthdays in the specified month
+    Returns a dictionary with years as keys and lists of projects as values
+    """
+    birthday_projects = defaultdict(list)
+    
+    for committee in committees_data:
+        # Skip if no established date
+        if "established" not in committee:
+            continue
+            
+        established = committee.get("established", "")
+        if not established or "-" not in established:
+            continue
+            
+        try:
+            est_year, est_month = established.split("-")
+            est_month = int(est_month)
+            est_year = int(est_year)
+            
+            # Check if the project's birthday is in the target month
+            if est_month == month:
+                project_name = committee.get("name", "Unknown Project")
+                project_id = committee.get("id", "")
+                homepage = committee.get("homepage", "")
+                description = committee.get("charter", "No description available")
+                
+                # Add project to the appropriate year group
+                birthday_projects[est_year].append({
+                    "name": project_name,
+                    "id": project_id,
+                    "established": established,
+                    "homepage": homepage,
+                    "description": description,
+                    "age": CONFIG["current_year"] - est_year
+                })
+        except (ValueError, IndexError):
+            # Skip entries with invalid date format
+            continue
+    
+    return birthday_projects
+
+def generate_birthday_summary(birthday_projects, month):
+    """Generate a markdown summary of projects with birthdays in the specified month"""
+    if not birthday_projects:
+        return f"# Apache Project Birthdays - {get_month_name(month)} {CONFIG['current_year']}\n\nNo Apache projects were established in {get_month_name(month)}.\n"
+    
+    month_name = get_month_name(month)
+    summary = f"# Apache Project Birthdays - {month_name} {CONFIG['current_year']}\n\n"
+    summary += f"The following Apache projects are celebrating their birthdays in {month_name}.\n\n"
+    
+    # Sort years in descending order (newest first)
+    sorted_years = sorted(birthday_projects.keys(), reverse=True)
+    
+    for year in sorted_years:
+        projects = birthday_projects[year]
+        # Sort projects within each year by name
+        projects.sort(key=lambda x: x["name"])
+        
+        for project in projects:
+            age = project["age"]
+            age_suffix = "year" if age == 1 else "years"
+            
+            summary += f"## {project['name']} ({age} {age_suffix})\n\n"
+            summary += f"**Established:** {project['established']}\n\n"
+            summary += f"**Description:** {project['description']}\n\n"
+            summary += f"**Project Homepage:** {project['homepage']}\n\n"
+            summary += "---\n\n"
+    
+    return summary
+
+def save_content(content, output_dir, month):
+    """Save the generated summary to a file"""
+    if not content:
+        return
+    
+    month_name = get_month_name(month).lower()
+    year = CONFIG["current_year"]
+    filename = f"apache_birthdays_{year}_{month:02d}_{month_name}.md"
+    filepath = output_dir / filename
+    
+    try:
+        with open(filepath, 'w') as f:
+            f.write(content)
+        logger.info(f"Birthday summary saved to {filepath}")
+        return filepath
+    except Exception as e:
+        logger.error(f"Error saving summary to {filepath}: {e}")
+        return None
+
+def send_notification(title, message):
+    """Send a macOS desktop notification"""
+    try:
+        import subprocess
+        script = f'display notification "{message}" with title "{title}"'
+        subprocess.run(["osascript", "-e", script], check=True)
+        logger.info(f"Desktop notification sent: {title} - {message}")
+    except Exception as e:
+        logger.error(f"Failed to send desktop notification: {e}")
+
+def main():
+    """Main function to fetch Apache project birthdays and generate a monthly summary"""
+    logger.info("Starting Apache project birthdays fetch")
+    output_dir = Path(CONFIG["output_dir"])
+    output_dir.mkdir(parents=True, exist_ok=True)
+    
+    # Get the current month or use the one specified in CONFIG
+    month = CONFIG["current_month"]
+    month_name = get_month_name(month)
+    
+    # Fetch committees data
+    committees_data = fetch_json_data(CONFIG["committees_url"])
+    
+    if not committees_data:
+        logger.error("Failed to fetch committees data")
+        send_notification("Apache Birthdays Fetch Failed", "Failed to fetch committees data")
+        return
+    
+    # Get projects with birthdays in the current month
+    birthday_projects = get_projects_with_birthdays(committees_data, month)
+    
+    # Generate and save birthday summary
+    summary = generate_birthday_summary(birthday_projects, month)
+    filepath = save_content(summary, output_dir, month)
+    
+    # Count total projects
+    total_projects = sum(len(projects) for projects in birthday_projects.values())
+    
+    # Log completion
+    logger.info(f"Found {total_projects} projects with birthdays in {month_name}")
+    logger.info("Apache project birthdays fetch completed")
+    
+    # Send notification
+    notification_message = f"Found {total_projects} Apache projects with birthdays in {month_name}"
+    send_notification("Apache Project Birthdays Summary Complete", notification_message)
+    
+    # Print path to the generated file
+    if filepath:
+        print(f"Birthday summary saved to: {filepath}")
+
+if __name__ == "__main__":
+    main()
diff --git a/project-activity/README.md b/project-activity/README.md
new file mode 100644
index 0000000..7134062
--- /dev/null
+++ b/project-activity/README.md
@@ -0,0 +1,54 @@
+# Apache Project Activity Reporter
+
+Generates activity reports for Apache Software Foundation projects by
+fetching mailing list archives and git repository metadata.
+
+## Requirements
+
+- [uv](https://github.com/astral-sh/uv) (dependencies are managed inline via the script header)
+- git
+
+## Usage
+
+```
+./project_activity.py -p <project> [-m <months>]
+```
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `-p`, `--project` | ASF project name (e.g., `iceberg`, `httpd`) | required |
+| `-m`, `--months` | Number of months of history | 3 |
+| `-h`, `--help` | Show help | |
+
+### Example
+
+```
+./project_activity.py -p iceberg -m 6
+```
+
+## What it does
+
+1. **Mailing lists** — Checks for common Apache list names (`dev`, `user`, `users`, `commits`, `issues`, `reviews`), then fetches mbox archives for the time period. Already-fetched past months are skipped if complete; the current month is always refetched.
+
+2. **Git repositories** — Discovers `apache/{project}` and `apache/{project}-*` repos on GitHub. Clones metadata-only (no file content). Existing clones are updated with `git pull`.
+
+3. **Report** — Generates a Markdown report with the top 5 most active threads per mailing list and commit counts per repository. Lists and repos with no activity are omitted.
+
+## Directory structure
+
+```
+project-activity/
+├── project_activity.py          # Main script
+├── README.md
+├── DATA/
+│   ├── mbox/
+│   │   └── <project>/
+│   │       └── <list>/          # e.g., dev/, issues/
+│   │           └── YYYY-MM.mbox # Monthly mbox archives
+│   └── REPOSITORIES/
+│       └── <project>/
+│           └── <repo>/          # Metadata-only git clones
+└── REPORTS/
+    └── <project>/
+        └── YYYY-MM-DD.md        # Datestamped activity reports
+```
diff --git a/project-activity/project_activity.py b/project-activity/project_activity.py
new file mode 100755
index 0000000..5a5c94b
--- /dev/null
+++ b/project-activity/project_activity.py
@@ -0,0 +1,322 @@
+#!/usr/bin/env -S uv run --script
+# /// script
+# dependencies = [
+#   "requests",
+# ]
+# ///
+
+import argparse
+import os
+import sys
+import subprocess
+import mailbox
+import email
+import requests
+from datetime import datetime, timedelta
+from collections import defaultdict
+from pathlib import Path
+
+DATA_DIR = Path(__file__).parent / "DATA"
+COMMON_LISTS = ["dev", "user", "users", "commits", "issues", "reviews"]
+
+
+def check_list_exists(project, list_name):
+    """Check if an Apache mailing list exists."""
+    domain = f"{project}.apache.org"
+    date = datetime.now().strftime("%Y-%m")
+    url = f"https://lists.apache.org/api/mbox.lua?list={list_name}@{domain}&date={date}"
+    try:
+        r = requests.get(url, timeout=10)
+        if r.status_code == 200 and len(r.content) > 100:
+            return True
+    except requests.RequestException:
+        pass
+    # Try a few months back
+    for i in range(1, 12):
+        d = datetime.now() - timedelta(days=30 * i)
+        url = f"https://lists.apache.org/api/mbox.lua?list={list_name}@{domain}&date={d.strftime('%Y-%m')}"
+        try:
+            r = requests.get(url, timeout=10)
+            if r.status_code == 200 and len(r.content) > 100:
+                return True
+        except requests.RequestException:
+            continue
+    return False
+
+
+def fetch_mbox(project, list_name, year_month):
+    """Fetch an mbox file for a given list and month. Returns path or None."""
+    domain = f"{project}.apache.org"
+    dest_dir = DATA_DIR / "mbox" / project / list_name
+    dest_dir.mkdir(parents=True, exist_ok=True)
+    dest = dest_dir / f"{year_month}.mbox"
+
+    now = datetime.now()
+    ym_parts = year_month.split("-")
+    target_year, target_month = int(ym_parts[0]), int(ym_parts[1])
+
+    # Determine if we should skip fetching
+    if dest.exists():
+        is_current_month = (target_year == now.year and target_month == now.month)
+        if is_current_month:
+            pass  # Always refetch current month
+        else:
+            # For past months, check if file was fetched after end of that month
+            end_of_month = datetime(target_year, target_month + 1, 1) if target_month < 12 else datetime(target_year + 1, 1, 1)
+            file_mtime = datetime.fromtimestamp(dest.stat().st_mtime)
+            if file_mtime > end_of_month:
+                return dest  # Already complete
+
+    url = f"https://lists.apache.org/api/mbox.lua?list={list_name}@{domain}&date={year_month}"
+    try:
+        r = requests.get(url, timeout=60)
+        if r.status_code == 200 and len(r.content) > 100:
+            dest.write_bytes(r.content)
+            return dest
+    except requests.RequestException as e:
+        print(f"  Warning: Failed to fetch {list_name}/{year_month}: {e}")
+    return None
+
+
+def fetch_mailing_lists(project, months):
+    """Discover lists and fetch mbox archives."""
+    print("Checking mailing lists...")
+    active_lists = []
+    for ln in COMMON_LISTS:
+        if check_list_exists(project, ln):
+            print(f"  Found list: {ln}")
+            active_lists.append(ln)
+
+    if not active_lists:
+        print("  No mailing lists found.")
+        return active_lists
+
+    now = datetime.now()
+    month_list = []
+    for i in range(months + 1):
+        d = now - timedelta(days=30 * i)
+        month_list.append(d.strftime("%Y-%m"))
+
+    for ln in active_lists:
+        print(f"  Fetching archives for {ln}...")
+        for ym in month_list:
+            result = fetch_mbox(project, ln, ym)
+            if result:
+                print(f"    {ym}: OK")
+            else:
+                print(f"    {ym}: no data")
+
+    return active_lists
+
+
+def discover_repos(project):
+    """Discover GitHub repos for apache/{project} and apache/{project}-*."""
+    repos = []
+    # Check main repo
+    try:
+        r = requests.get(f"https://api.github.com/repos/apache/{project}", timeout=10)
+        if r.status_code == 200:
+            repos.append(r.json()["name"])
+    except requests.RequestException:
+        pass
+
+    # Search for project-* repos
+    try:
+        url = f"https://api.github.com/search/repositories?q=org:apache+{project}-+in:name&per_page=100"
+        r = requests.get(url, timeout=10)
+        if r.status_code == 200:
+            for repo in r.json().get("items", []):
+                name = repo["name"]
+                if name.startswith(f"{project}-") and name not in repos:
+                    repos.append(name)
+    except requests.RequestException:
+        pass
+
+    return repos
+
+
+def fetch_repos(project, repos):
+    """Clone or update repos with metadata only."""
+    repo_dir = DATA_DIR / "REPOSITORIES" / project
+    repo_dir.mkdir(parents=True, exist_ok=True)
+
+    for repo_name in repos:
+        path = repo_dir / repo_name
+        git_url = f"https://github.com/apache/{repo_name}.git"
+        if path.exists():
+            print(f"  Updating {repo_name}...")
+            try:
+                subprocess.run(["git", "pull"], cwd=path, capture_output=True, check=True)
+            except subprocess.CalledProcessError as e:
+                print(f"    Warning: pull failed for {repo_name}: {e}")
+        else:
+            print(f"  Cloning {repo_name} (metadata only)...")
+            try:
+                subprocess.run(
+                    ["git", "clone", "--filter=blob:none", "--no-checkout", git_url, str(path)],
+                    capture_output=True, check=True,
+                )
+            except subprocess.CalledProcessError as e:
+                print(f"    Warning: clone failed for {repo_name}: {e}")
+
+
+def analyze_mbox_threads(project, list_name, months):
+    """Analyze mbox files and return top threads."""
+    now = datetime.now()
+    threads = defaultdict(int)  # subject -> message count
+
+    for i in range(months + 1):
+        d = now - timedelta(days=30 * i)
+        ym = d.strftime("%Y-%m")
+        path = DATA_DIR / "mbox" / project / list_name / f"{ym}.mbox"
+        if not path.exists():
+            continue
+        try:
+            mbox = mailbox.mbox(str(path))
+            for msg in mbox:
+                raw_subject = msg.get("Subject", "(no subject)")
+                # Decode MIME-encoded headers
+                decoded_parts = email.header.decode_header(raw_subject)
+                subject = ""
+                for part, charset in decoded_parts:
+                    if isinstance(part, bytes):
+                        subject += part.decode(charset or "utf-8", errors="replace")
+                    else:
+                        subject += part
+                # Collapse folded header whitespace and sanitize for markdown tables
+                subject = " ".join(subject.split())
+                subject = subject.replace("|", "\\|")
+                # Normalize: strip Re:/Fwd: prefixes
+                s = subject
+                while True:
+                    lower = s.lower().lstrip()
+                    if lower.startswith("re:") or lower.startswith("fwd:"):
+                        s = s.lstrip()[s.lstrip().index(":") + 1:].lstrip()
+                    elif lower.startswith("[") and "]" in lower:
+                        s = s[s.index("]") + 1:].lstrip()
+                    else:
+                        break
+                threads[s.strip()] += 1
+        except Exception:
+            continue
+
+    # Sort by count, top 5
+    top = sorted(threads.items(), key=lambda x: -x[1])[:5]
+    total = sum(threads.values())
+    return top, total
+
+
+def analyze_repo_commits(project, repo_name, months):
+    """Count commits in the past m months."""
+    path = DATA_DIR / "REPOSITORIES" / project / repo_name
+    if not path.exists():
+        return 0
+    since = (datetime.now() - timedelta(days=30 * months)).strftime("%Y-%m-%d")
+    try:
+        result = subprocess.run(
+            ["git", "rev-list", "--count", f"--since={since}", "HEAD"],
+            cwd=path, capture_output=True, text=True, check=True,
+        )
+        return int(result.stdout.strip())
+    except (subprocess.CalledProcessError, ValueError):
+        return 0
+
+
+def report(project, active_lists, repos, months):
+    """Generate a markdown activity report."""
+    today = datetime.now().strftime("%Y-%m-%d")
+    report_dir = Path(__file__).parent / "REPORTS" / project
+    report_dir.mkdir(parents=True, exist_ok=True)
+    report_path = report_dir / f"{today}.md"
+
+    lines = []
+    lines.append(f"# Apache {project} — Activity Report")
+    lines.append(f"")
+    lines.append(f"Generated: {today}  ")
+    lines.append(f"Period: {months} months ending {today}")
+    lines.append("")
+
+    # Mailing lists
+    any_list_activity = False
+    list_sections = []
+    for ln in active_lists:
+        top_threads, total = analyze_mbox_threads(project, ln, months)
+        if total == 0:
+            continue
+        any_list_activity = True
+        section = []
+        section.append(f"### {ln}@ ({total} messages)")
+        section.append("")
+        section.append("| Messages | Thread |")
+        section.append("|-------:|--------|")
+        for subject, count in top_threads:
+            section.append(f"| {count} | {subject} |")
+        section.append("")
+        list_sections.append("\n".join(section))
+
+    if any_list_activity:
+        lines.append("## Most active mailing list threads")
+        lines.append("")
+        lines.append("\n".join(list_sections))
+    else:
+        lines.append("## Most active mailing list threads")
+        lines.append("")
+        lines.append("No mailing list activity found.")
+        lines.append("")
+
+    # Repos
+    any_repo_activity = False
+    repo_rows = []
+    for repo_name in repos:
+        count = analyze_repo_commits(project, repo_name, months)
+        if count == 0:
+            continue
+        any_repo_activity = True
+        repo_rows.append(f"| {repo_name} | {count} |")
+
+    lines.append("## Repositories")
+    lines.append("")
+    if any_repo_activity:
+        lines.append("| Repository | Commits |")
+        lines.append("|------------|--------:|")
+        lines.extend(repo_rows)
+    else:
+        lines.append("No repository activity found.")
+    lines.append("")
+
+    content = "\n".join(lines)
+    report_path.write_text(content)
+    print(f"\nReport written to {report_path}")
+    print(content)
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Apache project activity report")
+    parser.add_argument("-p", "--project", required=True, help="ASF project name")
+    parser.add_argument("-m", "--months", type=int, default=3, help="Number of months (default: 3)")
+    args = parser.parse_args()
+
+    project = args.project.lower()
+    months = args.months
+
+    print(f"Project: {project}")
+    print(f"Months: {months}\n")
+
+    # 1. Mailing lists
+    active_lists = fetch_mailing_lists(project, months)
+
+    # 2. Git repos
+    print("\nDiscovering GitHub repositories...")
+    repos = discover_repos(project)
+    if repos:
+        print(f"  Found: {', '.join(repos)}")
+        fetch_repos(project, repos)
+    else:
+        print("  No repositories found.")
+
+    # 3. Report
+    report(project, active_lists, repos, months)
+
+
+if __name__ == "__main__":
+    main()