# 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/bench-coreutils.sh` must pass. Not "mostly pass." Not
"pass on your machine." Pass.

The moment fastwc is slower than GNU wc — or disagrees with it 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 one standing exception: the 1M-line case, where GNU wins by exactly
one millisecond because they ship hand-tuned AVX-512 assembly. Closing
that gap is the project's open goal, not your excuse to be slower
anywhere else.

### 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()`, and `count_words()` in
`src/main.c` are the entire point of this project. You may touch them
only if `./benchmarks/bench-coreutils.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 wc (the only oracle around,
and it's 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:

- Closing the 1M-line AVX-512 gap (the only loss on the board)
- Benchmark case coverage for `-m` and multiple files
- `bench-busybox.sh` CI on a machine that actually has busybox

Ambitious issues:

- A word counter that doesn't just tie GNU — it embarrasses it
- Bigger SWAR chunks, wider strides, less patience

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