readme-breakouts

Why this exists

GitHub restricted the stargazer list to repo admins and collaborators, in a change announced on 2026-06-30. The endpoint answered 404 when tried on 2026-09-30. Growth curves for other people's repos are now hard to get. README text is still public, so this study looks at that instead.

The question: among repos that broke out recently, what do the READMEs contain? "Breakout" here means a public, non-fork repo created in the 365 days up to 2026-09-30 with at least 1,000 stars that day. The search found 3,806 of them. The dataset is a stratified sample of 100, with every detector rule, hand check and limit written down in METHOD.md in the repository.

What the sample shows

Population estimates, with 95% intervals. The plain sample shares are within four points of these. Full tables are in REPORT.md in the repository.

The median README is 13,663 characters. The median pitch line is 11 words.

Of the 14 READMEs with a comparison-framed table, 4 compare against tools outside the project. The rest compare the project's own editions or options.

The sample was split into faster and slower climbers by stars per day. No feature differed once the 40 comparisons were corrected for. The smallest raw p-value was 0.033.

20 of the 100 READMEs are mostly Chinese. The heading and comparison rules match English words, so they undercount for those.

These are descriptions of one sample. They do not show that a feature causes stars.

Run it

git clone https://github.com/rishsadh/readme-breakouts && cd readme-breakouts
python -m readme_breakouts check README.md            # your README against the benchmark
python -m readme_breakouts check owner/repo           # fetch the README of a repo (needs GITHUB_TOKEN or the gh CLI)
python -m readme_breakouts check README.md --json     # every feature, machine readable
python -m readme_breakouts features README.md         # the detectors' raw output
python -m readme_breakouts report                     # the headline table
python -m readme_breakouts report --markdown          # the full report

# repeat the study, or run it on a new date
python -m readme_breakouts run                        # sample, fetch, analyze, report into data/<today>
python -m readme_breakouts sample --population data/2026-09-30/population.csv --dir data/redraw

run spaces API calls 3 seconds apart and waits 65 seconds after a 403 or 429. It reads through GITHUB_TOKEN, or through the gh command line if it is installed, and every call it makes is to a read endpoint.

The data

Everything is in data/2026-09-30/ in the repository:

• population.csv: all 3,806 breakout repos with stars, forks, dates, stars per day, kind and licence. Repo descriptions are read during analysis (they feed the kind rule) but are not published.
• sample.csv: the draw of 100 (plus reserves), with the SHA of the README that was read.
• features.csv: what each detector found in each of the 100 READMEs.
• summary.json: shares, intervals, sizes, and the faster versus slower comparison.
• hand-checks.csv: the places where a detector disagreed with a human read.

The README texts themselves are not included, because they belong to their authors. The same goes for repo descriptions: the tool reads them to assign a kind and does not write them to any file.

Limits

• It does not test for fake stars. The stargazer lists such a test needs are no longer public. A crude check that drops the 10 repos with the most stars per fork moved no share by more than 3.9 points, which is a weak signal.
• It says nothing about cause. Faster and slower climbers did not differ on any feature after correction, in a sample this size.
• It is one sample of 100 from one day, weighted towards AI tooling because that is most of what broke out in these 12 months.
• The detectors read one line at a time and know package-manager style install commands and no others. Hand checks found about 93% of pitch flags, 80% of install flags and 4 of 14 comparison flags to be what they claim. The details are in METHOD.md.
• The kinds that set the sample weights come from crude keyword rules.

Licence

MIT.