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](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.