From ee324904522398d6e272c84f8ca1dee9bc8b90fc Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Petr=20Balv=C3=ADn?= Date: Tue, 22 Sep 2026 01:48:23 +0200 Subject: [PATCH] docs: write the 2.0.0 migration guide into the changelog Assisted-by: GLM 5.3 Flash --- CHANGELOG.md | 60 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 60 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 4582b00..cac0f7a 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -229,6 +229,66 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 a leading dot, `interpres: .port: ...`; the message now reads `interpres: port: ...`, the shape `EncodeError.Path` already used. +### Migration from 1.x + +**The module path.** 2.0 lives at `sourcedock.dev/petrbalvin/interpres/v2`, +the suffix the Go toolchain requires of every major version 2 module. Change +every import and `go get` line: + +```sh +go get sourcedock.dev/petrbalvin/interpres/v2 +``` + +**TOML 1.1 only.** The acceptance contract is the TOML 1.1 corpus, and the +promise that every 1.0 document parses exactly as before is withdrawn. +Documents whose verdict changes are the ones 1.1 relaxed: `\e` and `\xHH` +escapes, times without seconds, multi-line inline tables with comments and a +trailing comma. Nothing that parsed in 1.x stops parsing, because the 1.1 +grammar contains the 1.0 one. + +**The output takes the 1.1 form.** A date-time writes seconds only when the +value carries them, a fraction drops its trailing zeros, and a long inline +table breaks across lines. A document written from the same value can come +out shorter; it re-parses to the same value. + +**Text methods on by default.** A type implementing +`encoding.TextMarshaler` or `encoding.TextUnmarshaler` now takes the text +path with no option to switch it off. A struct that implemented the +interface encodes as a string where it was a table before. `MarshalTOML` and +`UnmarshalTOML` still win. + +**One Go type per date-time kind.** Offset date-times hand back +`OffsetDateTime`, not a bare `time.Time`. Code that type-asserts the tree or +expects `time.Time` inside `UnmarshalTOML` needs the new wrapper; a +destination field of type `time.Time` keeps working. + +**The document carries what the map could not.** `Parse` returns a +`*Document` with the key order, the inline distinction and the comments; +`ParseMap` gives the plain `map[string]any` tree the old `Parse` returned. +The document is writable, and `Marshal` writes it back with its comments. + +**Renamed API.** `Encoder.GroupByKind(bool)` is `Encoder.Layout(kind)` with +`LayoutKindGrouped` (the old default) and `LayoutKindDeclaration` (the old +`false`); `UseLiteralMultiline` is `LiteralMultiline`. + +**Tag options.** `omitempty` follows encoding/json: it now also drops empty +strings, zero numbers, `false`, nil pointers and nil interfaces. `required` +demands a key at decode. `inline` forces the inline table form at encode. +`comment=text` carries a comment `EmitFieldComments` prints. + +**Errors.** `DecodeError.Path` is a `Path` (segments with a `String()` +renderer), `EncodeError.Path` the same type instead of a plain string, and +both messages render `interpres: server.ports[2]: ...` with one prefix. +`SyntaxError` gained `Offset`, `Column` and `SourceLine`. Decode errors into +a `Number`-carrying tree and the fixed-size array decode are new shapes a +match on the old messages would not see. + +**Decoding shapes.** `map[string]any` values merge into a non-empty map +destination; untagged embedded maps beyond the first stay empty; numbers can +stay literals under `UseNumber`; local date-times can decode into +`time.Time` under `LocalTimeLocation`. All three are opt-in or additive +except where noted above. + ## [1.1.0] - 2026-09-18 ### Added