fastwc/CONTRIBUTING.md

Contributing to fastwc

We're building the word counter GNU wc is still trying to be after forty years. If that sounds like your kind of project, keep reading.

The rules

These aren't guidelines. They're the deal.

1. The benchmark is the contract

./benchmarks/test-all.sh must pass. Not "mostly pass." Not "pass on your machine." Pass. Every suite — words (growing to 10M lines), lines (monsters included), and stdin — races fastwc against GNU coreutils wc, busybox wc, and toybox wc at microsecond resolution.

The moment fastwc is slower than any of them on a real race — or disagrees with any of them on a single count — your change does not ship. We did not spend this much effort being faster than a forty-year-old dependency museum just so you could add a strlen() in the hot loop.

The benchmark is honest about what it measures. Both sides are timed by a C timer, and a case the reference finishes in under 5 ms is startup, not throughput: fastwc must still count it right, but the case is reported as startup-bound and excluded from the averages. Raced cases allow a 2% dead-heat margin so a genuine tie can't flake on scheduler jitter. That margin exists because GNU's threaded counter occasionally dead-heats with us on mid-size files — it has never won a raced case, and no exception is carved out for it (see docs/PERFORMANCE.md).

2. C99, or don't bother

We compile with -Wall -Wextra and zero warnings. Zero. If the compiler is complaining, the compiler is right and you are wrong. We target C99 with POSIX extensions, not whatever your compiler vendor's imagination happens to ship this quarter.

3. No new dependencies. Ever.

The C standard library is the only thing we trust. No gettext. No gnulib. No libutf8pro with its own translation team. GNU wc needs a build system the size of a small country to count newlines. We need cc.

If your feature needs a library, the feature is too big. Make the feature smaller.

4. The hot path is sacred

count_stream(), count_newlines(), count_words(), and the SIMD kernels in src/main.c are the entire point of this project. You may touch them only if ./benchmarks/test-all.sh still passes afterward. Rules for the counting loops:

• fixed stride, no per-token function calls
• no allocation, no locking, no syscalls — the read is the only syscall
• branchless where it costs nothing; lookup tables are the foundation, not a hack
• if you make it "clearer" but 2x slower, it's not clearer, it's worse

5. Never suppress the truth

No casts to silence warnings. No -Wno-* flags to make the noise go away. No void* where a real type exists. If the type system is fighting you, you're fighting the design. Fix the design.

6. The codebase is one file. Keep it that way.

src/main.c is one file and it will stay one file. GNU wc needs forty-two translation units and a build system with its own mailing list. We have one file and we can read all of it in one sitting. If your feature needs a new file, your feature is over-engineered.

7. Tests are the benchmarks

There is no separate test suite, because the benchmark is the test suite — it checks correctness against GNU coreutils wc, busybox wc, and toybox wc (all three are wrong often enough to keep us humble) and speed in the same breath. Add a flag? It gets benchmarked. Change the counting? It gets benchmarked. The fail-fast scripts in benchmarks/ are your tests, and all of them must pass before you open a PR.

8. No AI slop

If it looks like ChatGPT wrote it, it gets rejected. We can tell. Write code like a human who's been doing this for a decade and is tired of GNU's excuses.

How to contribute

Pick something

Good first issues:

• Benchmark case coverage for -m and multiple files
• Move the 1B-line monster behind a flag so quick CI runs stay quick

Ambitious issues:

• A word counter that doesn't just beat GNU — it embarrasses it
• Wider strides, less patience, and a 10B-line monster

Send a PR

1. Fork the repo
2. Create a branch: feat/my-thing or fix/my-bug
3. Write code that follows the rules above
4. Run ./benchmarks/test-all.sh — everything must pass
5. Open a PR against main

PR requirements

• Build must pass with zero warnings: make && make release
• Benchmarks must pass: ./benchmarks/test-all.sh
• Follow STYLEGUIDE.md. The style is the law.
• No commented-out code. No dead code. No TODO without a date.
• Commit messages in imperative: Count newlines in 8-byte strides not Added newline counting optimization

What we won't merge

• Anything slower than GNU wc. We didn't come this far to tie.
• Dependencies. If it needs a library, it needs to not need a library.
• GNU-style bloat. Long options with help strings in fourteen languages. Translation infrastructure. "Enterprise" anything. This is a word counter, not a CRM.
• Abstract nonsense. Three layers of indirection to add a feature means the feature is too complicated. GNU wc is what happens when you let abstractions win.
• AI slop. See rule 8.

Communication

We don't have a Discord. We don't have a forum. We don't have a mailing list with a code of conduct and a weekly digest. Open an issue. Write a clear title, a reproduction case, and what you expected. We'll respond when we respond.

If you want to propose a major feature, open an issue first. Surprise PRs that rewrite the counting loops get closed without review — the benchmark is the referee, and it doesn't know you.

---

fastwc is 0.1.0. Everything is subject to change except the rules above.