petrbalvin/interpres
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 3 Wiki Activity

docs: document set and changelog

Browse Source 
Assisted-by: GLM 5.3 Flash
This commit is contained in:
petrbalvin
2026-08-19 18:44:00 +02:00
parent 8266dd6450
commit d12da6181d
8 changed files with 1114 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/API.md
+431
View File
@@ -0,0 +1,431 @@
# API
The library exports the surface below from the `sourcedock.dev/petrbalvin/interpres`
package. The snippets assume:
```go
import "sourcedock.dev/petrbalvin/interpres"
```
## Functions
### `func Parse(data []byte) (map[string]any, error)`
Decodes a TOML document into an untyped tree, using the value mapping in the
[Decoding](#decoding) section below. Returns `*SyntaxError` on a malformed
document. Input that is not valid UTF-8 is rejected before the parser runs.
Equivalent to `ParseContext(context.Background(), data)`.
```go
tree, err := interpres.Parse([]byte("title = \"x\"\nport = 8080\n"))
```
### `func ParseContext(ctx context.Context, data []byte) (map[string]any, error)`
The cancellable variant of `Parse`. An already-cancelled context returns
`ctx.Err()` before any work. During parsing the context is checked every 64
top-level statements, so a long document aborts without running to completion.
### `func Unmarshal(data []byte, v any) error`
Parses `data` and stores the result in the value pointed to by `v`, typically a
pointer to a struct or to `map[string]any`. Equivalent to
`UnmarshalContext(context.Background(), data, v)`.
```go
var cfg Config
if err := interpres.Unmarshal(data, &cfg); err != nil {
return err
}
```
### `func UnmarshalContext(ctx context.Context, data []byte, v any) error`
The cancellable variant of `Unmarshal`.
### `func Marshal(v any) ([]byte, error)`
Encodes a `struct` or `map[string]V` value, or a non-nil pointer to one, into a
TOML 1.0 document. The emission rules are in the [Encoding](#encoding) section
below. Equivalent to `MarshalContext(context.Background(), v)`.
```go
out, err := interpres.Marshal(cfg)
```
### `func MarshalContext(ctx context.Context, v any) ([]byte, error)`
The cancellable variant of `Marshal`. The context is checked before any work
and every 64 fields during the reflection walk.
## Decoding
### Value mapping
`Parse` and `Unmarshal` map TOML values to Go types as follows:
| TOML value | Go type in the parsed tree |
|---|---|
| string | `string` |
| integer | `int64` |
| float | `float64` |
| boolean | `bool` |
| offset date-time | `time.Time` |
| local date-time | `LocalDateTime` |
| local date | `LocalDate` |
| local time | `LocalTime` |
| array | `[]any` |
| table, inline table | `map[string]any` |
| array of tables | `[]map[string]any` |
When decoding into a struct, these values convert onto the destination's
concrete types: any integer or unsigned width, floats, slices, nested structs
and `map[string]T`.
### Target constraints
`Unmarshal` and `(*Decoder).Decode` write into a non-nil pointer:
- `*struct`, matched per the field rules below
- `*map[string]any` or `*map[string]T`, keys become map keys and values decode
into `T` recursively
- `*any`, receives the whole parsed tree unchanged
Anything else returns `interpres: decode target must be a non-nil pointer`.
### Field matching
For a struct destination, a TOML key matches a field as follows:
1. The `toml:"name"` tag, using the part before any comma. The literal `-`
excludes the field.
2. Without a tag, the lower-cased field name.
3. The key itself is lower-cased before lookup, so the match is
case-insensitive on both sides: `DATABASEURL` matches a field named
`DatabaseUrl`.
The match is exact after lower-casing. No separator is inserted, so a TOML key
`database_url` does not match a field named `DatabaseUrl`; tag such a field
(`toml:"database_url"`) or use the lower-cased name as the key. When two fields
resolve to the same name, the one declared later wins.
Unknown keys are ignored by default; see [Strict decoding](#strict-decoding).
### Numeric conversion
The parser produces `int64` for every integer and `float64` for every float.
The decoder converts to the destination type with explicit overflow checks:
| Destination kind | Rule |
|---|---|
| `int`, `int8`, `int16`, `int32`, `int64` | the `int64` value must not overflow the destination |
| `uint`, `uint8`, `uint16`, `uint32`, `uint64` | the value must be non-negative; `uint8`, `uint16` and `uint32` enforce their own maxima; `uint64` accepts any non-negative `int64` |
| `float32`, `float64` | copied verbatim; an integer also coerces, so TOML `5` decodes into `5.0` |
| `bool`, `string` | exact kind match only, no coercion across kinds |
| `time.Time` | offset date-times only; no implicit conversion to or from the local variants |
A conversion that the rules do not allow produces an error wrapped with the
offending key or index, for example `p: interpres: integer 300 overflows uint8`.
### Date-time values
Offset date-times decode into `time.Time` and keep their offset. The local
variants decode into `LocalDateTime`, `LocalDate` and `LocalTime`, whose
embedded `time.Time` is normalised to UTC (midnight UTC for a local date, the
zero date for a local time). There is no implicit conversion between the offset
and local kinds; assigning one to the other is an error.
### Arrays of tables
A `[[a]]` block parses into a `[]map[string]any` element of the tree. When the
destination is a slice, each element decodes into the slice's element type
(`[]struct` or `[]map[string]V`); a mismatch on one element surfaces as an
error wrapped with `[i]:` and the element index.
### Custom decoding: `Unmarshaler`
A type that wants full control of its decode implements:
```go
type Unmarshaler interface {
UnmarshalTOML(data any) error
}
```
`data` is whatever the parser produced for that key: `string`, `bool`, `int64`,
`float64`, `time.Time`, `LocalDateTime`, `LocalDate`, `LocalTime`, `[]any`, or
`map[string]any`. The method inspects the value and mutates its own receiver;
the decoder keeps whatever state the receiver stored.
The method is usually on a pointer receiver (`*T`). The decoder invokes it when
the destination type or its pointer implements the interface, so a
pointer-receiver implementation on an addressable struct field is found
automatically, and a nil pointer destination is allocated first. An error
returned from `UnmarshalTOML` halts the decode and propagates wrapped with the
key path, for example `addr: unmarshal: not a string`.
### Strict decoding
By default unknown keys are dropped silently. A `Decoder` built with
`DisallowUnknownFields` rejects them instead:
```go
err := interpres.NewDecoder().
DisallowUnknownFields().
Decode(data, &cfg)
```
A typo such as `database_urls` then fails with
`interpres: unknown field "database_urls" for main.Config` instead of a silent
default-zero run. Strictness applies to every struct the decode reaches, at any
depth, including struct elements inside slices; map destinations accept every
key by nature.
### Cancellation
`ParseContext`, `UnmarshalContext` and `(*Decoder).DecodeContext` accept a
`context.Context`. An already-cancelled context short-circuits with
`context.Canceled` before any work begins; afterwards the context is checked
every 64 top-level statements.
### Flow
```mermaid
sequenceDiagram
participant Caller
participant Unmarshal as Unmarshal
participant Parser as parser
participant Decoder as decoder
Caller->>Unmarshal: data, v
Unmarshal->>Parser: ParseContext(ctx, data)
Parser-->>Unmarshal: tree or *SyntaxError
Unmarshal->>Decoder: decode(tree, reflect value)
Decoder-->>Unmarshal: nil or wrapped field error
Unmarshal-->>Caller: error
```
## Encoding
### Input constraints
`Marshal` and `(*Encoder).Marshal` accept a `struct`, a `map[string]V`, or a
non-nil pointer to one, where `V` is any value `Marshal` itself understands. A
different top-level value fails:
| Input | Error |
|---|---|
| a bare scalar or array | `interpres: top-level value must be a struct or map[string]V, got <type>` |
| a nil `any` | `interpres: cannot marshal nil value` |
| a nil pointer | `interpres: cannot marshal nil pointer` |
### Field matching
Struct fields become TOML keys as follows:
1. The `toml:"name"` tag, using the part before any comma. The literal `-`
skips the field.
2. Without a tag, the lower-cased field name. The key emitted for a field named
`DatabaseUrl` is `databaseurl`; tag the field to emit `database_url`.
3. An anonymous (embedded) field without a tag is inlined into the parent
table; with a tag it is a regular field under that name.
Keys that match `[A-Za-z0-9_-]+` are emitted bare, all others quoted. A
`map[string]V` emits its keys in sorted order for deterministic output, and a
nil map emits nothing.
Note the asymmetry: the encoder inlines untagged embedded structs, while the
decoder expects them under their lower-cased type name. A struct with an
untagged embedded struct therefore does not round-trip through `Unmarshal` into
the same type.
### Group-by-kind layout
By default every table is emitted with its entries grouped by kind:
1. scalars (`string`, `int64`, `float64`, `bool`, `time.Time`,
`LocalDateTime`, `LocalDate`, `LocalTime`)
2. sub-tables (structs and `map[string]V` values)
3. arrays of tables (`[]struct` and `[]map[string]V`)
Within each group the order follows struct field declaration order, or sorted
key order for maps. This is the only layout that reliably re-parses to the same
tree: once a `[header]` is written, later scalars at the parent level would be
parsed as keys of the sub-table.
### Preserving declaration order
`GroupByKind(false)` on an `Encoder` walks the entries in declaration order
instead, emitting each header immediately before its content:
```go
out, err := interpres.NewEncoder().GroupByKind(false).Marshal(cfg)
```
The output remains parseable, but a scalar declared after a sub-table lands
under that sub-table's header when the document is read back. Use this layout
for presentation only, not when the output must round-trip.
### Custom encoding: `Marshaler`
A type that wants a non-default TOML shape implements:
```go
type Marshaler interface {
MarshalTOML() (any, error)
}
```
The returned value is encoded as if it had been passed in place of the
receiver, so it may be a scalar, a slice, an array of tables, or another
struct or map, including the `Marshaler` result of another type; the encoder
recurses. An error returned from `MarshalTOML` fails the marshal wrapped with
the key path, for example `interpres: server.port: bad timestamp`.
```go
type Port int
func (p Port) MarshalTOML() (any, error) {
return int64(p), nil
}
```
### Empty arrays
A nil slice is always omitted. An empty (length 0) array of tables is always
omitted, because TOML forbids an empty `[[a]]`. Other empty arrays emit as
`key = []` by default; `OmitEmptyArrays()` skips them as well, so
`[]string{}` is treated like a nil slice.
### Long strings
By default every string is emitted as a basic `"..."` string with the escapes
TOML requires, and a string containing a newline is emitted as an escaped
multi-line basic string. `UseLiteralMultiline(threshold)` switches strings that
contain a newline and are at least `threshold` bytes long to the literal
`'''...'''` form, which carries the newlines verbatim:
```go
out, err := interpres.NewEncoder().UseLiteralMultiline(80).Marshal(cfg)
```
Single-line strings keep the basic form regardless of the threshold, and a
threshold of `0` or less disables the option.
### Cancellation
`MarshalContext` and `(*Encoder).MarshalContext` accept a `context.Context`. The
context is checked before any work and every 64 fields during the reflection
walk.
### What is not preserved
The output is not byte-identical to any document that produced the value:
- comments are dropped, and whitespace inside expressions is normalised
- map keys are emitted in sorted order
- the choice between `[table]` headers and inline tables is not preserved
- strings use the basic quoted form unless the literal option above applies
- floats always carry a `.` or an exponent, so a float `1` is emitted as `1.0`
and stays distinguishable from the integer `1` across a round-trip; negative
zero is normalised to `0.0`
The output is guaranteed to re-parse through `Parse` into an equivalent value
tree. `Marshal` cannot encode cyclic data structures.
### Flow
```mermaid
sequenceDiagram
participant Caller
participant Marshal as Marshal
participant Walk as reflection walk
participant Emit as emitter
Caller->>Marshal: v any
Marshal->>Walk: build tomlDoc from struct or map
Walk-->>Marshal: tomlDoc or wrapped error
Marshal->>Emit: emitDoc(doc)
Emit-->>Marshal: bytes or error
Marshal-->>Caller: bytes, error
```
## Types
### `type SyntaxError struct{ Line int; Msg string }`
Describes a malformed TOML document; `Line` is 1-based and `Error()` renders as
`interpres: line N: msg`. Read the structured fields with a type assertion or
`errors.AsType`:
```go
if se, ok := errors.AsType[*interpres.SyntaxError](err); ok {
fmt.Println(se.Line, se.Msg)
}
```
### `type Decoder`
Configurable strictness for decoding, constructed with `NewDecoder`. Set up
with `DisallowUnknownFields`, then call `Decode` or `DecodeContext` any number
of times. A configured `Decoder` holds no per-call state and is safe for
concurrent use.
### `type Encoder`
Configurable emission policy, constructed with `NewEncoder`. The option state
is private; set it with the chainable methods, each of which returns the
encoder:
| Method | Default | Effect |
|---|---|---|
| `GroupByKind(v bool)` | `true` | group entries as scalars, then sub-tables, then arrays of tables; `false` preserves declaration order |
| `OmitEmptyArrays()` | off | skip `key = []` for empty scalar arrays |
| `UseLiteralMultiline(threshold int)` | `0` | emit multi-line strings of at least `threshold` bytes as literal `'''...'''` |
```go
out, err := interpres.NewEncoder().
GroupByKind(false).
OmitEmptyArrays().
UseLiteralMultiline(80).
MarshalContext(ctx, cfg)
```
A configured `Encoder` holds no per-call state; each `Marshal` or
`MarshalContext` call copies the options and is safe for concurrent use, as
long as no setter races with a call.
### `type Marshaler interface{ MarshalTOML() (any, error) }`
See [Custom encoding](#custom-encoding-marshaler).
### `type Unmarshaler interface{ UnmarshalTOML(data any) error }`
See [Custom decoding](#custom-decoding-unmarshaler).
### Date-time wrappers
```go
type LocalDateTime struct{ time.Time } // 1979-05-27T07:32:00
type LocalDate struct{ time.Time } // 1979-05-27
type LocalTime struct{ time.Time } // 07:32:00.999999
```
Each carries a `String()` method returning the TOML-canonical rendering, with
the fractional second zero-padded to nanosecond precision when present. The
types are produced by `Parse` and accepted by `Marshal`.
## Errors
The entry points return:
- `*SyntaxError` for a malformed document, with the 1-based line
- a plain error for everything else: a non-pointer decode target, a type
mismatch, an overflow, a marshal policy violation, a cancelled context
Decode and encode failures are wrapped with the key path or element index using
`fmt.Errorf`, so `errors.Is` and `errors.AsType` see through them.
## Notes
The exported surface is documented in godoc form in the source, and `go doc .`
run from the module root is the authority on signatures and types. This file
explains what the surface is for and how the parts fit together.
docs/ARCHITECTURE.md
+113
View File
@@ -0,0 +1,113 @@
# Architecture
How interpres is put together. Every file, package and arrow below exists in the
source tree; nothing is aspirational.
## Overview
interpres is one public library package, one command, and one example. The
library implements the whole of TOML 1.0, decoding and encoding, in the
standard library alone; the command wraps the parser for the toml-test
compliance harness, against which it stands at 185 valid and 371 invalid cases
with zero failures; the example demonstrates the API.
```mermaid
flowchart TD
CLI[cmd/interpres-decode<br/>toml-test adapter] --> API
EX[examples/basic<br/>usage demo] --> API
subgraph Lib [package interpres]
API[interpres.go<br/>public API and types]
API --> P[parser.go<br/>recursive-descent parser]
API --> DEC[decode.go<br/>tree onto Go values]
API --> ENC[encode.go<br/>Go values to TOML]
P --> N[number.go<br/>numeric tokens]
P --> DT[datetime.go<br/>date-time atoms and types]
end
```
The public API in `interpres.go` is a thin facade: every entry point funnels
into `ParseContext` for parsing and into the unexported `decoder` and `encoder`
for the reflection work. `parser.go` owns the grammar; it leans on
`number.go` and `datetime.go` for the two token families that need their own
strict validation.
## Packages
| Path | Responsibility |
|---|---|
| `.` (package `interpres`) | The whole library. `interpres.go` declares the exported surface (`Parse`, `Unmarshal`, `Marshal`, the `*Context` variants, `Decoder`, `Encoder`, `Marshaler`, `Unmarshaler`, `SyntaxError`, the local date-time types); everything below it is unexported. |
| `cmd/interpres-decode` | The toml-test adapter. Reads TOML on stdin, writes tagged JSON on stdout. Owns no parsing logic. |
| `examples/basic` | A runnable tour of the API. Documentation in executable form, not part of the library. |
Inside the library package, one file owns one concern:
| File | Responsibility |
|---|---|
| `parser.go` | The recursive-descent parser. Produces the `map[string]any` tree and enforces the structural rules of TOML 1.0 (table redefinitions, dotted keys, arrays of tables). Reports a 1-based line on failure. |
| `number.go` | Strict numeric tokens: integers in the four radixes with `_` separators, and floats including `inf` and `nan`. Rejects leading zeros, misplaced underscores and malformed fractions. |
| `datetime.go` | The three local date-time wrapper types and `parseDateTime`, which classifies a token into the four date-time kinds under the strict TOML grammar. |
| `decode.go` | Maps the parsed tree onto Go values by reflection: struct fields, maps, slices, scalar conversion with overflow checks, `Unmarshaler` dispatch. |
| `encode.go` | The reverse walk: builds an intermediate `tomlDoc` per table (which is what preserves declaration order and enables the group-by-kind partition) and then emits it as TOML. |
The boundary that matters: `parser.go` produces only untyped trees
(`map[string]any`, `[]any`, `[]map[string]any`, scalars); `decode.go` and
`encode.go` are the only files that touch `reflect`; the command never touches
either, it consumes `Parse` alone.
## Data flow
Decoding is parse, then one reflection walk. `SyntaxError` values are produced
inside `parser.go` and returned as-is; conversion errors are produced inside
`decode.go` and wrapped with the key path as they unwind.
```mermaid
sequenceDiagram
participant Caller
participant API as interpres.go
participant P as parser.go
participant D as decode.go
Caller->>API: Unmarshal(data, v)
API->>P: ParseContext(ctx, data)
P->>P: number and datetime atoms
P-->>API: map tree or *SyntaxError
API->>D: decode(tree, reflect value)
D-->>API: nil or wrapped field error
API-->>Caller: error
```
Encoding walks the other way. `encode.go` first builds a `tomlDoc` from the
value, then emits it; the two phases are why `GroupByKind` can reorder entries
without a second reflection pass, and why cancellation is checked during both.
```mermaid
sequenceDiagram
participant Caller
participant API as interpres.go
participant B as encode.go build
participant E as encode.go emit
Caller->>API: Marshal(v)
API->>B: build tomlDoc from struct or map
B-->>API: tomlDoc or error
API->>E: emitDoc(doc)
E-->>API: bytes or error
API-->>Caller: bytes, error
```
## State and lifetime
- The exported `Decoder` and `Encoder` hold configuration only. Every
`Decode`, `DecodeContext`, `Marshal` and `MarshalContext` call allocates its
own unexported worker, so a configured type is safe for concurrent use; the
setter methods are not, and must finish before the value is shared.
- The parser is allocated per `ParseContext` call; nothing is cached between
documents.
- The date-time wrappers are values, not pointers, and are immutable in use.
- Nothing in the library starts goroutines or holds locks; concurrency safety
comes from having no shared mutable state.
## Dependencies
None. `go.mod` declares the module and the Go version and carries no requires;
the library imports the standard library only, which is the point of the
project. The `toml-test` binary is a development and CI tool, never a module
dependency.
docs/CLI.md
+71
View File
@@ -0,0 +1,71 @@
# Command line
The reference below is taken from the program itself. `interpres-decode` is the
toml-test harness adapter, not a general-purpose tool: it takes no flags and no
arguments, reads one TOML document from stdin, and writes the toml-test
tagged-JSON form to stdout.
## Synopsis
```sh
interpres-decode < document.toml
```
Build it with `just build`, which compiles it into `bin/interpres-decode`, or
run it straight from the module directory with `just run`.
## Exit codes
| Code | Meaning |
|---|---|
| `0` | the document parsed, tagged JSON written to stdout |
| `1` | parse error, the document is malformed; the message goes to stderr |
| `2` | reading stdin failed, or a value has no tagged representation |
## Wire format
Tables become JSON objects, arrays become JSON arrays, and every scalar is
wrapped in an object with a `type` and a `value`:
```json
{
"title": {"type": "string", "value": "hello"},
"port": {"type": "integer", "value": "9090"},
"enabled": {"type": "bool", "value": "true"},
"ratio": {"type": "float", "value": "3.14"}
}
```
| TOML value | Tag | Rendering |
|---|---|---|
| string | `string` | the string verbatim |
| integer | `integer` | decimal |
| float | `float` | decimal, or `inf`, `-inf`, `nan` |
| boolean | `bool` | `true` or `false` |
| offset date-time | `datetime` | RFC 3339 with nanoseconds |
| local date-time | `datetime-local` | `1979-05-27T07:32:00` |
| local date | `date-local` | `1979-05-27` |
| local time | `time-local` | `07:32:00.999999` |
## Examples
Echo a small document through the adapter:
```sh
echo 'title = "hello"
[server]
host = "127.0.0.1"
port = 9090
' | ./bin/interpres-decode
```
The output is the equivalent value tree as one JSON object. Run the official
compliance suite against the binary:
```sh
just toml-test
```
That recipe needs the `toml-test` binary on `PATH`, installed with
`go install github.com/toml-lang/toml-test/cmd/toml-test@v1.6.0`. The full
reference for the library itself is [API.md](API.md).
docs/DEVELOPMENT.md
+108
View File
@@ -0,0 +1,108 @@
# Development
How to work on interpres.
## Prerequisites
- Go 1.27.0, the version the `go` directive in `go.mod` declares.
- [just](https://github.com/casey/just) for the recipes.
- The `toml-test` binary on `PATH` for the compliance recipe, installed with
`go install github.com/toml-lang/toml-test/cmd/toml-test@v1.6.0`.
The module has no third-party dependencies, so there is nothing else to fetch.
## Setup
```sh
git clone https://sourcedock.dev/petrbalvin/interpres.git
cd interpres
just build
just test
```
## Recipes
Every recipe in the project's justfile, and what it does. Taken from the file
itself, so the names and the list match it exactly; `just` with no arguments
prints the same list.
| Recipe | What it does |
|---|---|
| `just gates` | the definition of done: build, format check, vet, the test suite with the coverage floor, and the race detector |
| `just build` | compiles `./cmd/interpres-decode` into `bin/interpres-decode` |
| `just test` | the suite with no cache, then the coverage floor of 80 percent from `coverage.out` |
| `just race` | the same suite under the race detector |
| `just unit ./... TestName` | a fast scoped run for iterating; the second argument is a `-run` pattern, `.*` by default |
| `just fuzz FuzzParse . 30s` | time-boxed fuzzing of one target in exactly one package; `go test -fuzz` rejects `./...`; never a gate |
| `just bench` | benchmarks, `-benchmem -count=5`, on an idle machine only |
| `just fmt` | `gofmt -w .`, format in place |
| `just fmt-check` | `gofmt -l .`, zero diff |
| `just vet` | `go vet ./...` and `go fix -diff ./...` |
| `just run` | `go run ./cmd/interpres-decode`, reads TOML from stdin |
| `just dev` | the same run, for iterating |
| `just example` | `go run ./examples/basic`, the usage tour |
| `just toml-test` | builds the adapter and runs the official toml-test compliance suite against it |
| `just coverage-html` | `just test`, then `go tool cover -html` into `coverage.html` |
| `just install` | builds, then copies the binary into `~/.local/bin` (`BINDIR` overrides) |
| `just uninstall` | removes the installed binary |
| `just clean` | removes `bin/` and `coverage.out` |
## Running a single test
```sh
just unit ./... TestParseMultilineString
go test -run 'TestRejectsSpecInvalid/table_over_array' ./...
go test ./cmd/interpres-decode/
```
Add `-v` for the sub-test names, and `-race` when the change touches
concurrency. `-count=1` defeats the test cache when a result looks stale.
## Coverage
```sh
just test
go tool cover -func=coverage.out
just coverage-html
```
`just test` prints the total itself and fails below 80 percent, which is the
same floor CI enforces. The profile is `coverage.out`; the HTML map is
`coverage.html`. Both are ignored by git.
## Benchmarks
```sh
just bench
```
Benchmark on an idle machine, and compare only runs made in one process against
each other. The recipe sweeps `./...` five times with `-benchmem`.
## Debugging the build
```sh
go build -gcflags='-m' ./... # inlining decisions
go build -gcflags='-S' ./... # what the compiler generated
```
## Continuous integration
Workflows live in `.gitea/workflows/` and run on the project's own runners.
They are written by hand rather than through `just`, but they enforce the same
set of gates, so a green `just gates` locally is the fastest way to a green
pipeline.
| Workflow | Trigger | What it does |
|---|---|---|
| `test.yml` | push or pull request to `development` | format check, vet, modernisation, build, the test suite with the 80 percent coverage floor, then the toml-test compliance suite |
| `race.yml` | `workflow_dispatch`, by hand | the suite under the race detector; the same race gate `just gates` runs locally |
| `release.yml` | a `v*` tag | the same gates plus the race detector, then the Gitea release from the CHANGELOG section |
## Releases
Releases are cut by merging `development` into `main` and tagging `vX.Y.Z`. The
tag drives the release workflow: it validates the tag, runs the full gate set
including the race detector, extracts the matching `## [X.Y.Z]` section from
`CHANGELOG.md`, and publishes the release with that section as its body. A
library ships no binaries, so the release carries the notes and nothing else.