Example: documenting an upstream contribution end to end

This article exists to show the format. It is a real structure with placeholder content — replace it with your own work, or delete the folder entirely.

Why this format#

A claim is only useful if someone can check it. Every article here is built to carry three things alongside the prose:

1. The data, as a real file you can download from this domain.
2. The code that produced it, pinned to specific versions.
3. The upstream change, if the work resulted in one, linked to the merged pull request.

That combination is also what makes the work findable. A search engine reading this page sees structured records for the dataset, the source contribution and the author, all pointing at the same identity — not just a wall of text.

The change#

The original file walker was sequential:

def walk(root: Path) -> list[Path]:
    files = []
    for entry in root.rglob("*"):
        if entry.is_file() and not is_ignored(entry):
            files.append(entry)
    return files

On a repository with 80,000 files this spent almost all of its time blocked on stat calls. Replacing it with a bounded pool of workers, one subtree per task, removed most of that:

def walk(root: Path, workers: int = 8) -> list[Path]:
    subtrees = [p for p in root.iterdir() if p.is_dir()]
 
    with ThreadPoolExecutor(max_workers=workers) as pool:
        results = pool.map(_walk_subtree, subtrees)
 
    files = [f for group in results for f in group]
    files.extend(p for p in root.iterdir() if p.is_file() and not is_ignored(p))
    return sorted(files)

Results#

Median across all twelve repositories was 6.6x. Full results are in the attached CSV; the script that produced them is attached too.

What to do with this file#

Copy the folder, rename it, and edit the frontmatter. The fields are documented in content/articles/README.md. The only required ones are title, description, date and category — everything else is optional and simply does not render when omitted.