# Contributing
## Design concept (short version)
- **Ease of use first.** Few names, few lines for common jobs; every
capability is an opt-in Cargo feature or a plain-data `Options` field.
- **Options are plain data.** One `Options` struct, public fields, no
builder methods. New capabilities become new fields.
- **Features gate capabilities, never flip behavior.** A format feature
adds a format; a value-parser feature adds table format ids; nothing
changes the meaning of an already-valid input.
- **Filenames decide override order, extensions decide parsers** (last
claimer of an extension wins — built-in and custom formats alike).
- **The table stage is generic.** Format modules lower files to
`[[key, value, format], …]` rows; `parse_table` interprets them. Name
shared things `Table*`, not `Csv*`.
- **Provenance is a debug aid.** `trace()` labels carry no config
semantics.
- **No dot-path getter.** `value["a"]["b"]["c"]` is already safe —
missing keys chain as `Null` instead of panicking — so it fully
covers the need, and a `.get("a.b.c")` API would just be a second way
to do the same thing. node-config's `config.get('a.b.c')` only exists
because of JS history: `config.a.b.c` used to throw on an undefined
intermediate and `config?.a?.b?.c` didn't exist yet; Rust's `Index`
gives us the safe form natively.
The crate docs (`src/lib.rs` and the item docs it links) are the
behavioral spec; CLAUDE.md records the design decisions and their
reasons — read both before changing behavior. README.md is the
user-facing overview; keep it simple.
## Workflow (TDD, strictly in this order)
1. Spec the behavior in the crate docs (a design decision also goes in
CLAUDE.md).
2. Write the tests — fixture folder, integration test, doc tests —
against the spec.
3. Implement until the tests pass.
4. A user-visible change adds its line to `CHANGELOG.md` under the
unreleased version — breaking and behavior changes in its upgrade
section, with before/after code.
## Test layout
- One fixture per scenario: `tests/fixtures/<case>/` with `config/`
(the input), `expect.value.json` (the plain merged result) and
`expect.debug.log` (the `{:#?}` debug form of the whole trace, warnings
included — what `c4 --trace -f debug` prints). Error cases have `config/` only.
- Binary spreadsheet fixtures (`.xlsx`/`.ods`) are never hand-edited:
`cargo run --manifest-path tools/gen-sheets/Cargo.toml` (a
zero-dependency Rust tool) regenerates them all — plus the
`xlsx-sheets` example workbook — byte-deterministically; CI checks
the binaries match the generator.
- Option variants get their own case folder with copied config files —
never share one config between variant expectations.
- CLI cases: `tests/cli/<case>/` with `args.txt` and one `result.*`
file, compared byte-for-byte against the binary's stdout.
- Fixture-dependent tests are `#[cfg]`-gated on the features their
fixtures need; watch feature implications (`inet` implies
`ipv4`+`ipv6`+`cidr`, `macaddr` implies `macaddr8`, `datetime`
implies `date`+`time`) when writing `not(feature = …)` gates.
- Shape validators live in crate-private `src/valid.rs` with exhaustive
accept/reject unit tests next to them.
- Examples are standalone crates under `examples/<name>/` with a
committed `output.log`; regenerate the log whenever the example
changes.
## Commands
```sh
cargo test # default features
cargo test --all-features # every format + value parser
cargo test --features cli # builds the binary + CLI stdout cases
cargo test --no-default-features --features yaml # single-format build must pass
cargo test --doc # doc tests only
(cd examples/00_simple && cargo run) # standalone example crates
```
When touching feature-gated behavior, run the matrix: default,
`--all-features`, `--features cli`, each single format via
`--no-default-features`, and partial value-parser combinations
(`csv,inet`, `csv,datetime`, `csv,macaddr`, …). Everything must pass
with zero warnings.
## Releasing a new version
Publishing is automated: pushing a `v*` tag runs the full CI and, once it
passes, publishes to crates.io via Trusted Publishing (OIDC — there is no
token to manage).
1. Commit all your changes first — a clean working tree keeps the tag
accurate.
2. Bump `version` in `Cargo.toml` (the crates.io package is `c4-config`;
the lib/binary stay `c4`). `cargo publish` uses this version, so it
must not already be published. In `CHANGELOG.md`, replace the
version's `— unreleased` with the release date. CI checks that the
tag matches the `Cargo.toml` version.
3. Tag it **with a `v` prefix** matching the version — `v0.1.1`, **not**
`0.1.1`. Only `v*` tags trigger the release workflow (`on.push.tags:
["v*"]`).
```sh
git tag v0.1.1
```
4. Push the commit and the tag. Pushing the tag kicks off CI; the
`publish` job runs `cargo publish` only after fmt + clippy, the MSRV
check, the whole test matrix and the examples all pass:
```sh
git push && git push --tags
```
Notes:
- The README install is `cargo add c4-config` (unpinned), so no version
string there needs updating.
- If the release raises the minimum toolchain, bump `rust-version` in
`Cargo.toml` and the MSRV job in `.github/workflows/main.yml` together.