4 files changed, 117 insertions, 16 deletions
diff --git a/doc/manual/src/SUMMARY.md.in b/doc/manual/src/SUMMARY.md.in
index b1c551969..964091285 100644
--- a/doc/manual/src/SUMMARY.md.in
+++ b/doc/manual/src/SUMMARY.md.in
@@ -67,6 +67,7 @@
   - [CLI guideline](contributing/cli-guideline.md)
 - [Release Notes](release-notes/release-notes.md)
   - [Release X.Y (202?-??-??)](release-notes/rl-next.md)
+  - [Release 2.14 (2023-02-28)](release-notes/rl-2.14.md)
   - [Release 2.13 (2023-01-17)](release-notes/rl-2.13.md)
   - [Release 2.12 (2022-12-06)](release-notes/rl-2.12.md)
   - [Release 2.11 (2022-08-25)](release-notes/rl-2.11.md)
diff --git a/doc/manual/src/contributing/cli-guideline.md b/doc/manual/src/contributing/cli-guideline.md
index 01a1b1e73..e53d2d178 100644
--- a/doc/manual/src/contributing/cli-guideline.md
+++ b/doc/manual/src/contributing/cli-guideline.md
@@ -389,6 +389,88 @@ colors, no emojis and using ASCII instead of Unicode symbols). The same should
 happen when TTY is not detected on STDERR. We should not display progress /
 status section, but only print warnings and errors.
 
+## Returning future proof JSON
+
+The schema of JSON output should allow for backwards compatible extension. This section explains how to achieve this.
+
+Two definitions are helpful here, because while JSON only defines one "key-value"
+object type, we use it to cover two use cases:
+
+ - **dictionary**: a map from names to value that all have the same type. In
+   C++ this would be a `std::map` with string keys.
+ - **record**: a fixed set of attributes each with their own type. In C++, this
+   would be represented by a `struct`.
+
+It is best not to mix these use cases, as that may lead to incompatibilities when the schema changes. For example, adding a record field to a dictionary breaks consumers that assume all JSON object fields to have the same meaning and type.
+
+This leads to the following guidelines:
+
+ - The top-level (root) value must be a record.
+
+   Otherwise, one can not change the structure of a command's output.
+
+ - The value of a dictionary item must be a record.
+
+   Otherwise, the item type can not be extended.
+
+ - List items should be records.
+
+   Otherwise, one can not change the structure of the list items.
+
+   If the order of the items does not matter, and each item has a unique key that is a string, consider representing the list as a dictionary instead. If the order of the items needs to be preserved, return a list of records.
+
+ - Streaming JSON should return records.
+
+   An example of a streaming JSON format is [JSON lines](https://jsonlines.org/), where each line represents a JSON value. These JSON values can be considered top-level values or list items, and they must be records.
+
+### Examples
+
+
+This is bad, because all keys must be assumed to be store implementations:
+
+```json
+{
+  "local": { ... },
+  "remote": { ... },
+  "http": { ... }
+}
+```
+
+This is good, because the it is extensible at the root, and is somewhat self-documenting:
+
+```json
+{
+  "storeTypes": { "local": { ... }, ... },
+  "pluginSupport": true
+}
+```
+
+While the dictionary of store types seems like a very complete response at first, a use case may arise that warrants returning additional information.
+For example, the presence of plugin support may be crucial information for a client to proceed when their desired store type is missing.
+
+
+
+The following representation is bad because it is not extensible:
+
+```json
+{ "outputs": [ "out" "bin" ] }
+```
+
+However, simply converting everything to records is not enough, because the order of outputs must be preserved:
+
+```json
+{ "outputs": { "bin": {}, "out": {} } }
+```
+
+The first item is the default output. Deriving this information from the outputs ordering is not great, but this is how Nix currently happens to work.
+While it is possible for a JSON parser to preserve the order of fields, we can not rely on this capability to be present in all JSON libraries.
+
+This representation is extensible and preserves the ordering:
+
+```json
+{ "outputs": [ { "outputName": "out" }, { "outputName": "bin" } ] }
+```
+
 ## Dialog with the user
 
 CLIs don't always make it clear when an action has taken place. For every
diff --git a/doc/manual/src/release-notes/rl-2.14.md b/doc/manual/src/release-notes/rl-2.14.md
new file mode 100644
index 000000000..705c118bb
--- /dev/null
+++ b/doc/manual/src/release-notes/rl-2.14.md
@@ -0,0 +1,22 @@
+# Release 2.14 (2023-02-28)
+
+* A new function `builtins.readFileType` is available. It is similar to
+  `builtins.readDir` but acts on a single file or directory.
+
+* In flakes, the `.outPath` attribute of a flake now always refers to
+  the directory containing the `flake.nix`. This was not the case for
+  when `flake.nix` was in a subdirectory of e.g. a Git repository.
+  The root of the source of a flake in a subdirectory is still
+  available in `.sourceInfo.outPath`.
+
+* In derivations that use structured attributes, you can now use `unsafeDiscardReferences`
+  to disable scanning a given output for runtime dependencies:
+  ```nix
+  __structuredAttrs = true;
+  unsafeDiscardReferences.out = true;
+  ```
+  This is useful e.g. when generating self-contained filesystem images with
+  their own embedded Nix store: hashes found inside such an image refer
+  to the embedded store and not to the host's Nix store.
+
+  This requires the `discard-references` experimental feature.
diff --git a/doc/manual/src/release-notes/rl-next.md b/doc/manual/src/release-notes/rl-next.md
index 7e8344e63..091d12b7e 100644
--- a/doc/manual/src/release-notes/rl-next.md
+++ b/doc/manual/src/release-notes/rl-next.md
@@ -1,22 +1,18 @@
 # Release X.Y (202?-??-??)
 
-* A new function `builtins.readFileType` is available. It is similar to
-  `builtins.readDir` but acts on a single file or directory.
+* The special handling of an [installable](../command-ref/new-cli/nix.md#installables) with `.drv` suffix being interpreted as all of the given [store derivation](../glossary.md#gloss-store-derivation)'s output paths is removed, and instead taken as the literal store path that it represents.
 
-* The `builtins.readDir` function has been optimized when encountering not-yet-known
-  file types from POSIX's `readdir`. In such cases the type of each file is/was
-  discovered by making multiple syscalls. This change makes these operations
-  lazy such that these lookups will only be performed if the attribute is used.
-  This optimization affects a minority of filesystems and operating systems.
+  The new `^` syntax for store paths introduced in Nix 2.13 allows explicitly referencing output paths of a derivation.
+  Using this is better and more clear than relying on the now-removed `.drv` special handling.
 
-* In derivations that use structured attributes, you can now use `unsafeDiscardReferences`
-  to disable scanning a given output for runtime dependencies:
-  ```nix
-  __structuredAttrs = true;
-  unsafeDiscardReferences.out = true;
+  For example,
+  ```shell-session
+  $ nix path-info /nix/store/gzaflydcr6sb3567hap9q6srzx8ggdgg-glibc-2.33-78.drv
   ```
-  This is useful e.g. when generating self-contained filesystem images with
-  their own embedded Nix store: hashes found inside such an image refer
-  to the embedded store and not to the host's Nix store.
 
-  This requires the `discard-references` experimental feature.
+  now gives info about the derivation itself, while
+
+  ```shell-session
+  $ nix path-info /nix/store/gzaflydcr6sb3567hap9q6srzx8ggdgg-glibc-2.33-78.drv^*
+  ```
+  provides information about each of its outputs.