interpres/CONTRIBUTING.md

Contributing

Thanks for your interest in interpres. This is a small, dependency-free TOML parser for Go; contributions that keep it focused, correct, and standard-library-only are welcome.

Ground rules

• Standard library only. No third-party Go modules — that constraint is the point of the project.
• Formatted and vetted. just build must pass cleanly (go vet, gofmt, compile). just test must be green.
• Tested. New syntax support or decoding behaviour comes with table-driven tests in interpres_test.go, and must not regress toml-test compliance.

Branches and releases

• main holds released code only. It is never committed to directly.
• development is the integration branch where work lands.

Open pull requests against development. A release is cut by merging development into main and pushing a vX.Y.Z tag to main; CI does not perform the merge. Bump the version in CHANGELOG.md (with the date and a tag link) as part of the release.

Releases follow Semantic Versioning.

Development

just build      # go vet + gofmt check + compile
just test       # run the Go test suite
just run        # run examples/basic
just coverage   # write an HTML coverage report

TOML 1.0 compliance

The bar for this parser is passing the official toml-test suite. cmd/interpres-decode speaks the harness protocol (TOML on stdin, tagged JSON on stdout, non-zero exit on invalid input):

go build -o interpres-decode ./cmd/interpres-decode
toml-test ./interpres-decode

Run this before and after any parser change; it must stay at zero failures.

Project structure

interpres/
├── interpres.go          # public API: Parse, Unmarshal, Marshal, Decoder, Encoder, SyntaxError
├── parser.go             # recursive-descent parser → map[string]any
├── number.go             # strict numeric token parsing
├── datetime.go           # date-time types and parsing
├── decode.go             # reflection mapping of the tree onto Go values
├── encode.go             # reflection-based marshal of Go values to TOML
├── interpres_test.go     # parser/decoder test suite
├── encode_test.go        # encoder test suite
├── cmd/interpres-decode/ # toml-test harness adapter
└── examples/basic/       # runnable usage example

Adding syntax or types

1. Extend parser.go / number.go / datetime.go (for syntax) or decode.go (for new destination types).
2. Add focused tests covering both the happy path and malformed input.
3. Confirm toml-test still reports zero failures.
4. If behaviour or the public API changes, update README.md and CHANGELOG.md.

Commit messages

Use Conventional Commits (feat:, fix:, docs:, refactor:, test:, chore:).