Contributing
The rules here are unusual, because the project is unusual. It is a port judged against a test suite it is not allowed to touch, and most of what follows exists to keep that claim honest.
The four things that are not negotiable
tests/original/ is never edited. Not to fix a test, not to skip one, not to adjust
whitespace. The hashes are pinned in tests/original/hashes.txt and verified at ship. If a
test genuinely cannot pass, it stays failing and gets an entry in
the decision log. A 94% pass rate you can reproduce beats a 100% claim you
cannot.
The shipped library contains no C. No cc crate, no bindgen, no build.rs compiling
anything, nothing under crates/ linking against upstream. The fuzz oracle is upstream's C
in a separate executable spoken to over a pipe. If you find yourself wanting to link it in
for speed, the answer is no, and Where the C ends
explains why.
No third-party CBOR crate. Not ciborium, not serde_cbor, not minicbor, not half.
Wrapping an existing crate is not a port. cbor-core uses core and alloc and nothing
else.
cbor-core stays #![forbid(unsafe_code)]. Every unsafe block lives in cbor-ffi
and carries a // SAFETY: line naming the invariant the C caller must uphold. make lint
recomputes the count and fails if a block loses its line, so this is enforced rather than
requested.
Before you open a PR
$ make test # 4,929 / 4,929, and the port's own differential tests
$ make lint # clippy, the unsafe budget check, and relative links
$ make fmt # rustfmt --check
$ make symbols # 44/44 exported, zero nm diff against upstream
All four, green. If you touched the parser or the encoder, also run the fuzzer for longer than the default minute:
$ TARGET=encode_diff DURATION=900 make fuzz
Sixty seconds is enough to say you fuzzed. It is not enough to find anything. Both real divergences found so far needed either fifteen minutes or a target that had never run before.
run.sh appends a row to fuzz/history.tsv when it finishes, so a long run you did is
recorded even though the log it wrote gets overwritten by the next one. Leave that row in
your PR; it is the only evidence the run happened.
make lint also resolves every relative link in the book, readme.md and decisions.md,
and fails on the first one pointing at a file that is not there. mdBook turns a broken link
into a 404 without complaining, so a rotted page looks exactly like a healthy one until
somebody clicks it.
Changing behaviour
The equivalence claim is against upstream at commit 9441b2ca. That has a consequence
people find surprising: if upstream has a bug, this port keeps it.
Two are documented. cbor_value_to_json_advance does not validate UTF-8 although its own
header says it does, which is
intel/tinycbor#331 and
decision 17. cbor_encode_simple_value accepts simple value 24 and emits
f8 18, which upstream's own parser then rejects, which is
decision 22.
Fixing either would turn a passing differential fuzz into a failing one and make the central claim of the project false. If upstream takes a fix, this follows. Until then, a divergence would be ours, not theirs.
So: a PR that makes this port better than upstream is a PR that has to argue its case in the decision log first.
Writing style
The code is read by people, so it is written for them.
- Comments explain why, and name the spec section when there is one (
RFC 8949 §3.2.1). - A comment that restates the line below it gets deleted.
- Plain engineering voice. No "this function is responsible for", no "robust", no "leverages".
Result<T, CborError>and?, never a translated errno. Where a C function returns an out-parameter plus a status, the Rust one returns the value.
The decision log is the other half of this. Every non-obvious divergence gets an entry at the moment you make it. Reconstructing them later is how you end up with ten empty bullets, and it shows.
Commits
Conventional Commits, scoped to the module:
fix(parser): leave the cursor where a failed string walk stopped
test(port): differential test for the caller-supplied reader source
docs(decisions): the upstream UTF-8 bug, and why this port keeps it
Scopes in use: parser, encoder, ffi, pretty, tojson, cbordump, json2cbor,
port, original, fuzz, bench, docs.
Write the body as though the reader has the diff but not your afternoon. What was wrong, what it did to a caller, how it was found. The commit log is the best record of the work this project has.
Adding a test
Tests for what upstream's suite does not reach go in tests/port/, and they follow one
pattern: the same source is built twice, once against each archive, and the two
transcripts are diffed.
No expected-output file. An expected-output file is a snapshot of what the code did on the day you wrote it, and it drifts into being a snapshot of a bug. Diffing against upstream cannot drift, because upstream is the specification here.
That pattern has found five bugs so far, none of which any fuzzer would have reached, and decision 18 is the write-up of the worst of them.
Next steps
- Building for the target list.
- Troubleshooting when a gate fails for environmental reasons.
- The decision log before you argue with any of the above.