Functory
functory.
All Articles
7 min read
Functory

Compute Bug-to-Feature Ratio from GitHub Issue CSVs in Python for Sprint Retrospectives

Founders and engineering leads often need a compact metric for sprint retrospectives: the bug-to-feature ratio (BFR) for a milestone. This article shows a practical, repeatable Python implementation that ingests a GitHub issues CSV export (the CSV you download from GitHub issues), classifies each row as a bug or a feature, and returns a robust BFR with breakdowns usable in automated reports and APIs such as a Functory function.

We cover expected CSV schema, deterministic classification (labels + title heuristics), edge cases (pull requests, unlabeled issues), a runnable code example, and how to deploy it as a paid Functory API for recurring retrospectives.

What this function expects and produces

Input (CSV): a GitHub issues CSV export. Typical columns used in this workflow:

  • id (integer) — GitHub issue number
  • title (string)
  • body (string)
  • labels (string) — comma- or semicolon-delimited labels like "bug,help wanted"
  • state (string) — "open" or "closed"
  • milestone (string) — milestone title (e.g., "Sprint 2025-01")
  • created_at, closed_at (ISO 8601 timestamps)
  • is_pull_request (optional boolean) — some CSVs include a pull_request flag; otherwise detect via "Pull Request" in title or missing body patterns

Processing steps:

  • Filter rows to the requested milestone and optionally to a date window.
  • Exclude pull requests.
  • Classify each issue as bug, feature, or other using label whitelist + title/description heuristics.
  • Aggregate counts, compute ratio = bugs / max(features, 1) and produce breakdown JSON with sample issue IDs.

Output (JSON-serializable dict):

{
  "milestone": "Sprint 2025-01",
  "bug_count": 14,
  "feature_count": 36,
  "ratio": 0.3889,
  "sample_bugs": [45, 71, 123],
  "sample_features": [66, 77, 88]
}

Real-world scenario (concrete inputs & outputs)

Scenario: a small B2B marketplace with a 6-person engineering team exports issues.csv for milestone "Sprint 2025-01" containing 1,200 rows (including PR entries). Columns include: id,title,body,labels,state,milestone,created_at,closed_at. Founder wants an automated endpoint that returns a BFR and top unlabeled bugs to prompt labeling in the next retro.

Example concrete input: issues.csv (1,200 rows), filtering to milestone = "Sprint 2025-01" leaves 250 rows. After excluding 40 pull request entries, classification yields:

  • bug_count = 22
  • feature_count = 60
  • ratio = 0.3667

Output JSON (returned from the API):

{
  "milestone": "Sprint 2025-01",
  "bug_count": 22,
  "feature_count": 60,
  "ratio": 0.3667,
  "unlabeled_count": 10,
  "notes": "10 issues had no labels; consider retro action to label them."
}

Example dataset and specific problem

Fabricated dataset: 1,000 issues rows covering 8 milestones. Columns are exactly: id,int | title,str | body,str | labels,str | state,str | milestone,str | created_at,str | closed_at,str | user_login,str.

Problem: manual spreadsheet labeling and counting takes ~2 hours per sprint for the founder and is error-prone. The automated function converts this into a single API call producing the BFR and a list of issues missing important labels (bug/feature), enabling a 1-click retro task list.

Step-by-step mini workflow

  1. Export issues CSV from GitHub: Issues → Filters → Export CSV.
  2. Call the BFR function (local script or Functory API) with CSV and milestone name.
  3. The function filters milestone rows, excludes PRs, classifies each issue, and aggregates counts.
  4. Receive JSON response and post to Slack or save to your BI dashboard.
  5. Optionally open the list of unlabeled issues and batch-apply labels in GitHub UI or via API.

Algorithm (high-level)

  1. Load CSV into a dataframe and normalize labels field to lowercase, split on commas/semicolons.
  2. Filter rows to milestone == requested_milestone and state in {"open","closed"}.
  3. Mark and exclude pull requests: look for "pull request" flags, "PR" prefixes, or presence of "pull_request" column.
  4. Classify each issue: if any label in bug_labels -> bug; elif any label in feature_labels -> feature; else title/body regex heuristics: look for keywords like "bug", "error", "crash" for bugs and "add", "support", "enhancement" for features; otherwise mark as other/unlabeled.
  5. Aggregate counts, compute ratio = bug_count / max(feature_count, 1), return JSON with counts and example issue IDs for manual review.

Python code example

The snippet below is a compact, runnable example using pandas. It reads a CSV, classifies issues, and prints a JSON-like dict suitable to return from a Functory main(...) function.

import re
from typing import List, Dict
import pandas as pd

BUG_LABELS = {"bug", "type: bug"}
FEATURE_LABELS = {"enhancement", "feature", "type: enhancement"}

def classify_issue(labels: str, title: str, body: str) -> str:
    labels_set = {l.strip().lower() for l in re.split(r"[;,]", labels) if l.strip()} if labels else set()
    if labels_set & BUG_LABELS:
        return "bug"
    if labels_set & FEATURE_LABELS:
        return "feature"
    text = (title or "") + "\n" + (body or "")
    if re.search(r"\b(error|crash|bug|exception|fail)\b", text, re.I):
        return "bug"
    if re.search(r"\b(add|support|implement|enhanc)\b", text, re.I):
        return "feature"
    return "other"

def compute_bfr(csv_path: str, milestone: str) -> Dict:
    df = pd.read_csv(csv_path, dtype=str).fillna("")
    df = df[df["milestone"] == milestone]

    # exclude pull requests if identifiable
    if "is_pull_request" in df.columns:
        df = df[df["is_pull_request"].astype(str).str.lower() != "true"]
    else:
        df = df[~df["title"].str.lower().str.contains(r"^pull request|^pr|merge", na=False)]

    df["classification"] = df.apply(lambda r: classify_issue(r.get("labels",""), r.get("title",""), r.get("body","")), axis=1)
    bug_count = int((df["classification"] == "bug").sum())
    feature_count = int((df["classification"] == "feature").sum())

    return {
        "milestone": milestone,
        "bug_count": bug_count,
        "feature_count": feature_count,
        "ratio": round(bug_count / max(feature_count, 1), 4),
        "sample_bugs": df[df["classification"]=="bug"]["id"].astype(int).head(5).tolist(),
    }

# Example call
if __name__ == "__main__":
    summary = compute_bfr("issues.csv", "Sprint 2025-01")
    print(summary)

How Functory Makes It Easy

To publish this as a Functory function, wrap the core logic above in a single main(...) entrypoint that accepts typed parameters: main(csv_path: FilePath, milestone: str) and returns a JSON-like dict. On Functory you must choose an exact Python version (for example, 3.11.11) and provide a requirements.txt where every dependency is pinned, e.g.:

pandas==2.2.2

Structure your file so Functory invokes main(...) directly; do not use CLI parsing. Inputs become UI fields and API JSON fields (the CSV can be uploaded in the UI or passed as a URL string), and the return value becomes the API response. Functory provides autoscaling, CPU/GPU tiers (if you later do heavier processing), built-in logging via print(), and pay-per-use billing — so you have no servers to manage. You can also chain this function on Functory: e.g., pre-processing -> compute BFR -> post results to Slack with a second function.

Alternatives and why a function-based approach wins

Developers commonly compute BFRs by: (a) manual spreadsheet filtering, (b) ad-hoc Jupyter notebooks, (c) using Jira built-in reports, or (d) BI tools like Looker connected to a sync of GitHub data. Manual and notebook approaches are brittle and not easily callable by non-technical stakeholders. BI tools require a data warehouse and ETL overhead. A focused, single-file function exposed as an API combines reproducibility, low operational cost, and programmatic access for automated retros, reducing manual steps while remaining simple to maintain.

Industry context

According to a 2024 developer operations survey, ~68% of small engineering teams report spending 1–3 hours per sprint on manual issue triage or reporting (source: "2024 DevOps Processes Study", simulated citation). Automating the BFR calculation converts that time into an API call.

Business benefit

Concrete benefit: converting a 2-hour manual process to an automated API reduces founder/engineer time spent on reporting by ~60% (2 hours → ~30 minutes monthly for verification), and enables consistent metrics across customers. For a small team billing $60/hr effective fully-loaded cost, this is approx. $72 saved per sprint in direct labor, and faster decision cycles for product prioritization.

Comparison with other approaches

Spreadsheets: easy but error-prone and not repeatable. Notebooks: reproducible but require technical ownership and manual runs. Warehouse + BI: powerful but costly and slow to iterate. A single-file function that can be hosted as a Functory API sits between these: low cost, reproducible, callable programmatically, and suitable for paid marketplace delivery.

Conclusion

We built a practical pattern to compute bug-to-feature ratio from GitHub issue CSV exports using deterministic classification rules and a small pandas-based function. Next steps: extend the classifier with severity weighting, add automated GitHub label patches for unlabeled issues, or publish the function on Functory as a monetized API. Try converting your next sprint's issues.csv with the example above and publish the function so teammates can call the metric from Slack or your dashboard.

Thanks for reading.