Release KDL 2.0.0

kdl-org · Dec 15, 2024 · 5d6f755 · 5d6f755
1 parent 0e58f61
commit 5d6f755
Show file tree

Hide file tree

Showing 3 changed files with 117 additions and 93 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,52 +1,6 @@
 # KDL Changelog
 
-## 2.0.0-draft.8 (2024-12-14)
-
-* Some details have been clarified around the treatment of whitespace in
-  multiline strings.
-* `raw-string` productions have been updated to be explicitly non-greedy and
-  "fallible".
-* Some tests have been added, others adjusted, some removed, after a cleanup pass.
-
-## 2.0.0-draft.7 (2024-12-10)
-
-* `node-space` is now allowed as whitespace after a `slashdash`, meaning line
-  continuations will work now.
-* One or two consecutive double-quotes are now allowed in the bodies of
-  multi-line quoted strings, without needing to be escaped.
-* Grammar has been fixed to disallow raw strings like `#"""#`, which are now
-  properly treated as invalid multi-line raw strings (instead of the equivalent of
-  `"\""`).
-* Test suite has been updated to include a `_fail` suffix in all test cases
-  which are expected to fail.
-* A slew of additional slashdash and multi-line string compliance tests have
-  been added. Have fun. :)
-* The organization of string types in the spec prose has been updated to a
-  hopefully more helpful structure.
-
-
-## 2.0.0-draft.6 (2024-12-04)
-
-* Multiline strings, both Raw and Quoted, must now use `"""` instead of a single `"`. Using `"""` for a single-line string is a syntax error.
-* Fixed an issue with the `unicode_silly` test case.
-* Some rewordings and clarification in the spec prose.
-* Slight grammar tweak where the pre-terminator `node-space*` for `node` and `final-node` have been moved into `base-node`.
-
-
-## 2.0.0-draft.5 (2024-11-28)
-
-* Equals signs other than `=` are no longer supported in properties.
-* 128-bit integer type annotations have been added to the list of "well-known"
-  type annotations.
-* Multiline string escape rules have been tweaked significantly.
-* `\s` is now a valid escape within a string, representing a space character.
-* Slashdash (`/-`)-compatible locations and related grammar adjusted to be more
-  clear and intuitive. This includes some changes relating to whitespace,
-  including comments and newlines, which are breaking changes.
-* Various updates to test suite to reflect changes.
-
-
-## 2.0.0 (Unreleased)
+## 2.0.0 (2024-12-16)
 
 ### Grammar
 
@@ -71,6 +25,7 @@
   improvement.
 * Raw strings no longer require an `r` prefix: they are now specified by using
   `#""#`.
+* Raw string productions are now explicitly non-greedy (and "fallible").
 * Line continuations can be followed by an EOF now, instead of requiring a
   newline (or comment). `node \<EOF>` is now a legal KDL document.
 * `#` is no longer a legal identifier character.
@@ -91,7 +46,7 @@
   should be valid UTF-8 now, as was intended.
 * The last node in a child block no longer needs to be terminated with `;`,
   even if the closing `}` is on the same line, so this is now a legal node:
-  `node {foo;bar;baz}`
+  `node{foo;bar;baz}`
 * More places allow whitespace (node-spaces, specifically) now. With great
   power comes great responsibility:
   * Inside `(foo)` annotations (so, `( foo )` would be legal (`( f oo )` would
@@ -123,6 +78,10 @@
 
 ### KQL
 
+> [!INFO] Note: these are provided for convenience, but as of the 2.0.0 KDL spec release,
+> KQL itself is not finalized and should be considered a separate specification,
+> alongside the Schema spec and others.
+
 * There's now a _required_ descendant selector (`>>`), instead of using plain
   spaces for that purpose.
 * The "any sibling" selector is now `++` instead of `~`, for consistency with
@@ -131,3 +90,54 @@
 * Multi- and single-line comments are now supported, as well as line
   continuations with `\`.
 * Map operators have been removed entirely.
+
+---
+
+## 2.0.0 Draft Changelogs
+
+### 2.0.0-draft.8 (2024-12-14)
+
+* Some details have been clarified around the treatment of whitespace in
+  multiline strings.
+* `raw-string` productions have been updated to be explicitly non-greedy and
+  "fallible".
+* Some tests have been added, others adjusted, some removed, after a cleanup pass.
+
+
+### 2.0.0-draft.7 (2024-12-10)
+
+* `node-space` is now allowed as whitespace after a `slashdash`, meaning line
+  continuations will work now.
+* One or two consecutive double-quotes are now allowed in the bodies of
+  multi-line quoted strings, without needing to be escaped.
+* Grammar has been fixed to disallow raw strings like `#"""#`, which are now
+  properly treated as invalid multi-line raw strings (instead of the equivalent of
+  `"\""`).
+* Test suite has been updated to include a `_fail` suffix in all test cases
+  which are expected to fail.
+* A slew of additional slashdash and multi-line string compliance tests have
+  been added. Have fun. :)
+* The organization of string types in the spec prose has been updated to a
+  hopefully more helpful structure.
+
+
+### 2.0.0-draft.6 (2024-12-04)
+
+* Multiline strings, both Raw and Quoted, must now use `"""` instead of a single `"`. Using `"""` for a single-line string is a syntax error.
+* Fixed an issue with the `unicode_silly` test case.
+* Some rewordings and clarification in the spec prose.
+* Slight grammar tweak where the pre-terminator `node-space*` for `node` and `final-node` have been moved into `base-node`.
+
+
+### 2.0.0-draft.5 (2024-11-28)
+
+* Equals signs other than `=` are no longer supported in properties.
+* 128-bit integer type annotations have been added to the list of "well-known"
+  type annotations.
+* Multiline string escape rules have been tweaked significantly.
+* `\s` is now a valid escape within a string, representing a space character.
+* Slashdash (`/-`)-compatible locations and related grammar adjusted to be more
+  clear and intuitive. This includes some changes relating to whitespace,
+  including comments and newlines, which are breaking changes.
+* Various updates to test suite to reflect changes.
+
diff --git a/README.md b/README.md
@@ -1,16 +1,9 @@
 # The KDL Document Language
 
-> [!WARNING]  
-> The main branch of this repository shows the latest v2.0.0 draft, which is a
-> work in progress and not considered the "mainline" KDL yet. Most KDL
-> implementations in the wild are based on the [v1.0.0
-> spec](https://github.com/kdl-org/kdl/tree/1.0.0) instead, so you may want to
-> refer to that if you're using KDL today.
-
 KDL is a small, pleasant document language with XML-like node semantics that
 looks like you're invoking a bunch of CLI commands! It's meant to be used both
-as a serialization format and a configuration language, much like JSON, YAML,
-or XML. It looks like this:
+as a serialization format and a configuration language, much like JSON, YAML, or
+XML. It looks like this:
 
 ```kdl
 package {
@@ -51,27 +44,34 @@ package {
 }
 ```
 
+For more details, see the [overview below](#overview).
+
 There's a living [specification](SPEC.md), as well as various
 [implementations](#implementations). You can also check out the [FAQ](#faq) to
 answer all your burning questions!
 
-The current version of the KDL spec is `2.0.0-draft.8`.
+The current version of the KDL spec is `2.0.0`. For legacy KDL, please refer to
+the [KDL 1.0 spec](./SPEC_v1.md). All users are encouraged to migrate.
+[Migration is forward-and-backward-compatible and
+safe](./SPEC.md#compatibility), and can be automated.
 
-In addition to a spec for KDL itself, there are also standard specs for [a KDL
-Query Language](QUERY-SPEC.md) based on CSS selectors, and [a KDL Schema
+In addition to a spec for KDL itself, there are specifications for [a KDL Query
+Language](QUERY-SPEC.md) based on CSS selectors, and [a KDL Schema
 Language](SCHEMA-SPEC.md) loosely based on JSON Schema.
 
 The language is based on [SDLang](https://sdlang.org), with a [number of
 modifications and clarifications on its syntax and behavior](#why-not-sdlang).
+We are grateful for their work as an inspiration to ours.
 
-[Play with it in your browser!](https://kdl-play.danini.dev/)
+[Play with it in your browser (currently v1 only)!](https://kdl-play.danini.dev/)
 
 ## Design and Discussion
 
-KDL 2.0 design is still in progress. Discussions and questions about the format
-should happen over on the [discussions
-page](https://github.com/kdl-org/kdl/discussions). Feel free to jump in and give
-us your 2 cents!
+KDL 2.0.0 has been finalized, and no further changes are expected. For questions
+about KDL and discussions, please see the [discussions
+page](https://github.com/kdl-org/kdl/discussions). For minor editorial fixes or
+critical spec errata, please feel free to [file an
+issue](https://github.com/kdl-org/kdl/issues).
 
 ## Used By
 
@@ -92,26 +92,39 @@ of some examples of KDL in the wild (either v1, v2, or both):
 
 ## Implementations
 
-* Rust: [kdl-rs](https://github.com/kdl-org/kdl-rs), [knuffel](https://crates.io/crates/knuffel/) (latter includes derive macro), and [kaydle](https://github.com/Lucretiel/kaydle) (serde-based)
-* JavaScript: [kdljs](https://github.com/kdl-org/kdljs), [@virtualstate/kdl](https://github.com/virtualstate/kdl) (query only, JSX based)
-* Ruby: [kdl-rb](https://github.com/danini-the-panini/kdl-rb)
-* Dart: [kdl-dart](https://github.com/danini-the-panini/kdl-dart)
-* Java: [kdl4j](https://github.com/hkolbeck/kdl4j)
-* PHP: [kdl-php](https://github.com/kdl-org/kdl-php)
-* Python: [kdl-py](https://github.com/tabatkins/kdlpy), [cuddle](https://github.com/djmattyg007/python-cuddle), [ckdl](https://github.com/tjol/ckdl)
-* Elixir: [kuddle](https://github.com/IceDragon200/kuddle)
-* XSLT: [xml2kdl](https://github.com/Devasta/XML2KDL)
-* Haskell: [Hustle](https://github.com/fuzzypixelz/Hustle)
-* .NET: [Kadlet](https://github.com/oledfish/Kadlet)
-* C: [ckdl](https://github.com/tjol/ckdl)
-* C++: [kdlpp](https://github.com/tjol/ckdl) (part of ckdl, requires C++20)
-* OCaml: [ocaml-kdl](https://github.com/Bannerets/ocaml-kdl)
-* Nim: [kdl-nim](https://github.com/Patitotective/kdl-nim)
-* Common Lisp: [kdlcl](https://github.com/chee/kdlcl)
-* Go: [gokdl](https://github.com/lunjon/gokdl), [kdl-go](https://github.com/sblinch/kdl-go)
-* Swift: [kdl-swift](https://github.com/danini-the-panini/kdl-swift)
-* Crystal: [kdl-cr](https://github.com/danini-the-panini/kdl-cr)
-* Lua: [kdlua](https://github.com/danini-the-panini/kdlua)
+> [!INFO] There are two major versions of KDL. Different libraries may support one or the
+> other, or even provide a "hybrid" mode where both versions are attempted, since
+> there's no data ambiguity between v1 and v2 documents.
+
+| Language | Implementation | v1 | v2 | Notes |
+|---|---|---|---|---|
+| C | [ckdl](https://github.com/tjol/ckdl) | ✅ | ✅ | |
+| C#/.NET | [Kadlet](https://github.com/oledfish/Kadlet) | ✅ | ✖️ | |
+| C++ | [kdlpp](https://github.com/tjol/ckdl) | ✅ | ✅ | part of ckdl, requires C++20 |
+| Common Lisp | [kdlcl](https://github.com/chee/kdlcl) | ✅ | ✖️ | |
+| Crystal | [kdl-cr](https://github.com/danini-the-panini/kdl-cr) | ✅ | ✖️ | |
+| Dart | [kdl-dart](https://github.com/danini-the-panini/kdl-dart) | ✅ | ✖️ | |
+| Elixir | [kuddle](https://github.com/IceDragon200/kuddle) | ✅ | ✅ | |
+| Go | [gokdl](https://github.com/lunjon/gokdl) | ✅ | ✖️ | |
+| Go | [kdl-go](https://github.com/sblinch/kdl-go) | ✅ | ✖️ | |
+| Haskell | [Hustle](https://github.com/fuzzypixelz/Hustle) | ✅ | ✖️ | |
+| Java | [kdl4j](https://github.com/hkolbeck/kdl4j) | ✅ | ✖️ | |
+| JavaScript | [@virtualstate/kdl](https://github.com/virtualstate/kdl) | ✅ | ✖️ | query only, JSX based |
+| JavaScript | [kdljs](https://github.com/kdl-org/kdljs) | ✅ | ✖️ | |
+| Lua | [kdlua](https://github.com/danini-the-panini/kdlua) | ✅ | ✖️ | |
+| Nim | [kdl-nim](https://github.com/Patitotective/kdl-nim) | ✅ | ✖️ | |
+| OCaml | [ocaml-kdl](https://github.com/Bannerets/ocaml-kdl) | ✅ | ✖️ | |
+| PHP | [kdl-php](https://github.com/kdl-org/kdl-php) | ✅ | ✖️ | |
+| Python | [ckdl](https://github.com/tjol/ckdl) | ✅ | ✅ | |
+| Python | [cuddle](https://github.com/djmattyg007/python-cuddle) | ✅ | ✖️ | |
+| Python | [kdl-py](https://github.com/tabatkins/kdlpy) | ✅ | ✅ | |
+| Ruby | [kdl-rb](https://github.com/danini-the-panini/kdl-rb) | ✅ | ✖️ | |
+| Rust | [kdl-rs](https://github.com/kdl-org/kdl-rs) | ✅* | ✅ | Format/comment-preserving parser |
+| Rust | [knuffel](https://crates.io/crates/knuffel/) | ✅ | ✖️ | Serde-_style_ derive macros (not actual Serde) | 
+| Swift | [kdl-swift](https://github.com/danini-the-panini/kdl-swift) | ✅ | ✖️ | |
+| XSLT | [xml2kdl](https://github.com/Devasta/XML2KDL) | ✅ | ✖️ | |
+
+\* Supported by earlier library version
 
 ## Compatibility Test Suite
 
@@ -123,11 +136,11 @@ entirety, but in the future, may be required to in order to be included here.
 
 ## Editor Support
 
-* [VS Code](https://marketplace.visualstudio.com/items?itemName=kdl-org.kdl&ssr=false#review-details)
+* [Intellij IDEA](https://plugins.jetbrains.com/plugin/20136-kdl-document-language)
 * [Sublime Text](https://packagecontrol.io/packages/KDL)
+* [TreeSitter](https://github.com/tree-sitter-grammars/tree-sitter-kdl) (neovim, among others)
+* [VS Code](https://marketplace.visualstudio.com/items?itemName=kdl-org.kdl&ssr=false#review-details)
 * [vim](https://github.com/imsnif/kdl.vim)
-* [neovim](https://github.com/tree-sitter-grammars/tree-sitter-kdl)
-* [Intellij IDEA](https://plugins.jetbrains.com/plugin/20136-kdl-document-language)
 
 ## Overview
 

diff --git a/SPEC.md b/SPEC.md
@@ -1,14 +1,15 @@
 # KDL Spec
 
-This is the semi-formal specification for KDL, including the intended data
-model and the grammar.
+This is the formal specification for KDL, including the intended data model and
+the grammar.
 
-This document describes KDL version `2.0.0-draft.8`. It was released on
-2024-12-14.
+This document describes KDL version `2.0.0`. It was released on 2024-12-16. It
+is the latest stable version of the language, and will only be edited for minor
+copyedits or major errata.
 
 ## Compatibility
 
-KDL v2 is designed such that for any given KDL document written as [KDL
+KDL 2.0 is designed such that for any given KDL document written as [KDL
 1.0](./SPEC_v1.md) or KDL 2.0, the parse will either fail completely, or, if the
 parse succeeds, the data represented by a v1 or v2 parser will be identical.
 This means that it's safe to use a fallback parsing strategy in order to support