# Contributing to zig-http What someone changing this library needs to know that the [README](README.md) does not already say. The README explains what the library is and how it is tested; this is about how to work on it. ## Where to send things Issues and pull requests go to the Tangled mirror: - Issues: - Pull requests: The repository also lives on Forgejo and on Radicle (see [Where this lives](README.md#where-this-lives)), and all three carry the same history, but Tangled is where reports and changes are read. A bug report is most useful with the octets that caused it. Almost every layer of this library can be driven from a slice of memory, so a request, a response or a frame sequence pasted into the report usually becomes the regression test for its fix. ## The development environment Everything comes from the flake, including the Zig it is built with: ```console $ nix develop ``` `main` builds with Zig 0.17.0. The `zig-0.16` branch is the last release for Zig 0.16.0 and takes critical fixes only. ## Before sending a change These are what CI runs, and a change should pass all of them: ```console $ reuse lint $ zig fmt --check --exclude zig-pkg --exclude interop/https-records/zig-pkg . $ zig build test --summary all $ zig build check $ zig build fuzz-run -- --iterations 60000 $ (cd interop/https-records && zig build test --summary all) ``` `zig build check` compiles what no test builds — the fuzz driver, the documentation server and the demonstration program — so that one of them cannot quietly stop compiling. The `interop/https-records` project is separate because it depends on zig-dns-client, which depends on this library; see [its build file](interop/https-records/build.zig). `nix flake check` runs the NixOS virtual machine tests described in [The virtual machine tests](README.md#the-virtual-machine-tests). They need KVM and take a while, so CI runs them on every push and running them by hand is worth it when a change touches what a real peer sees on the wire. ## Tests Unit tests live next to the code they test. The suites under `tests/` drive whole exchanges; the README's [Building and testing](README.md#building-and-testing) says which does what. **Every public function has a doctest.** A doctest is a test named by the function, `test name { ... }`, in the same container as the function, which is what the generated documentation shows as its example. Write it the way a caller would use the function, with `std.testing.expect*` assertions on what comes back. A few things about them are easy to get wrong: - A test inside a nested type is only compiled if that type is analyzed. If the test count does not go up by the number of tests added, the container needs a `test { std.testing.refAllDecls(@This()); }` or a `_ = Type;` to reach it. `-Dtest-filter=` is the quick way to see whether a test runs. - A doctest name has to resolve unambiguously. Where it cannot — a method sharing a name with a function in an enclosing scope — write a string-named test instead and say why in a comment. - A test that writes to stderr fails the build step even when its assertions pass, so take any debugging output out before committing. A bug fix comes with a test that fails without the fix. Name such a test after the rule it pins — `test "RFC 9114 4.1.2: a response to HEAD carries its length and no content"` — and check that it really does fail on the old code, since a test that never failed proves nothing. Tests that need a socket listen on `.loopback(0)` and connect to themselves. The `Io` is `std.testing.io`; `transport.memory` and `transport.memory_session.Scripted` stand in for a connection or a QUIC session where a test does not need a real one. The README states how many tests there are. Keep it right, counting from a clean `.zig-cache`: a build that reuses cached results counts only the tests it ran. ## Fuzzing `tests/fuzz.zig` holds the targets, each a property rather than an example (see [Fuzzing](README.md#fuzzing)). A new parser, or a new path through an existing one that takes input from a peer, wants a target or a seed for one. For a longer search than CI does: ```console $ zig build fuzz-run -- --seconds 600 ``` A finding is saved as a file and reported with its path; anything else that goes wrong is the tooling rather than a finding. ## Dependencies Zig dependencies are added and moved with the package manager: ```console $ zig fetch --save= git+https://...# ``` pinned to a commit. The Nix build cannot fetch, so after any change to `build.zig.zon` regenerate the expression it builds from, and commit both: ```console $ zon2nix --17 --nix=build.zig.zon.nix build.zig.zon ``` The `tls` pin has to be the one zig-quic uses, so that the two resolve to one module and their types are the same types. Moving zig-quic means checking its `build.zig.zon` and moving `tls` with it if it moved. ## How the code is written The [four layers](README.md#the-four-layers) and the [two modules](README.md#two-modules-and-which-one-you-want) are the design, and a change should keep to them: `http` is the protocol and owns no file descriptor, and every octet reaches it through a `transport.Connection` or a `transport.Session`. Anything that needs a socket belongs in `http_io`. Nothing a peer sends may make this library panic. Check a value before narrowing it into a smaller integer, since `@intCast` of out-of-range input is a panic rather than an error, and treat every length a peer declares as a claim to be checked against a limit. The doc comments carry most of the explanation in this library, and the published [API documentation](README.md#api-documentation) is generated from them. A change that alters what a function does updates its doc comment in the same commit. Where a rule comes from a specification, cite the section — `§4.1.2 of RFC 9114` — and quote it when the wording matters. Use the terms [GLOSSARY.md](GLOSSARY.md) defines, and American spelling. ## Licensing The project is MIT licensed and follows [REUSE](https://reuse.software/). A new file starts with the SPDX header the others have; a file that cannot hold one, such as a generated file or test data, is covered in `REUSE.toml` instead. `reuse lint` checks both. ## Commit messages The subject is a sentence saying what the change does — "Reset an HTTP/2 stream whose body fell short of its declared length" — and the body says why: what was wrong, how it showed, and what the fix is. One logical change per commit. ## Releases A release sets the version in `build.zig.zon` and `package.nix`, commits that, and tags the commit with a signed, annotated `vX.Y.Z` tag whose message says in a line what the release brings. Before 1.0.0 the minor version goes up when public API is removed or changed incompatibly, and the patch version for anything else.