# 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](https://semver.org).

## Development

```sh
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](https://github.com/toml-lang/toml-test) suite. `cmd/interpres-decode`
speaks the harness protocol (TOML on stdin, tagged JSON on stdout, non-zero exit
on invalid input):

```sh
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](https://www.conventionalcommits.org/) (`feat:`,
`fix:`, `docs:`, `refactor:`, `test:`, `chore:`).