How OSS Chronicles works

OSS Chronicles treats a software repository as an archaeological site rather than a code dump.

A chronicle starts from primary sources—commits, pull requests, issues, releases, RFCs, and source code—then adds contemporary project blogs, talks, mailing lists, forums, and ecosystem context. The goal is to reconstruct the causal story behind the software: what pressure existed, what options were available at the time, why a choice was made, and what that choice cost later.

Reading model

The main narrative is intentionally finite: usually 8–12 chapters and roughly 30,000–50,000 Chinese characters for a mature project. Technical rabbit holes live in optional deep dives instead of bloating the main story.

A strong chapter follows a causal chain:

pressure → debate → experiment → decision → implementation → consequence

Evidence model

The writing distinguishes between three levels of certainty:

• Fact — directly supported by a primary source.
• Contemporary explanation — a maintainer or participant publicly explained the motivation.
• Inference — a reasonable interpretation based on evidence, explicitly labeled as such.

Narrative energy is welcome. Invented dialogue, invented motives, and fake historical scenes are not.

Visuals

Architecture diagrams, timelines, and before/after diagrams should clarify technical change. Prefer factual SVG diagrams that can be reviewed in Git. Generated editorial illustrations are optional and must never masquerade as historical evidence.