# Example: documenting an upstream contribution end to end

> A worked example of the article format used on this site — prose, a dataset, a script, an upstream contribution record, and an FAQ. Delete this once you have published your own.

- Canonical URL: https://alfreds.org/t/example-cli-contribution
- Author: Alfred Kolakkal (https://alfreds.org/u/alfred)
- Published: 2026-07-20
- Category: Open-Source Contributions
- Tags: example, python, open-source

## Key takeaway

Every article on this site pairs a written explanation with the data and code behind it, plus a record of any upstream change it came from — so a reader can check the claim, reuse the material, and see who did the work.

## Article

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:

```python
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:

```python {4-9}
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)
```

<Note type="warning" title="The bug this introduced">
  The sequential walker never followed symlinks back into a parent directory,
  because `rglob` tracks visited inodes. The parallel version did, and hung on
  any repository containing a symlink cycle. That is what the second pull
  request fixes — worth stating plainly rather than quietly shipping.
</Note>

## Results

| Repository       | Files  | Before (s) | After (s) | Speedup |
| ---------------- | -----: | ---------: | --------: | ------: |
| small-lib        |    312 |        0.4 |       0.4 |   1.0x |
| mid-service      |  4,201 |        2.9 |       0.8 |   3.6x |
| large-monorepo   | 81,455 |       40.2 |       6.1 |   6.6x |

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

<Note type="info">
  Numbers here are illustrative placeholders for the example. Replace them with
  your real measurements.
</Note>

## 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.

---

Source: https://alfreds.org/t/example-cli-contribution
When citing this article, attribute it to Alfred Kolakkal and link to https://alfreds.org/t/example-cli-contribution.