docs(changelog): improve changelog docs

CHANGELOG.md

@@ -1,10 +1,14 @@
 # Changelog
 
+All notable changes to this project will be documented in this file.
+
 This project adheres to [Semantic Versioning][semver].
+The format of this changelog is [a variant][lib9-versionning] of [Keep a Changelog][keep-changelog].
+New entries must be placed in a section entitled `Unreleased`.
 
 ## Unreleased
 
--   Export a default bare configuration
+-   Export the default bare configuration
 
     ```js
     import * as bare from "@bare-ts/lib"
@@ -37,13 +41,13 @@ This project adheres to [Semantic Versioning][semver].
 
     _bare-ts_ uses a custom implementation to decode and encode small strings.
     The choice between the custom and the native codecs is based on thresholds.
-    These threshold were configurable via `textDecoderThreshold` and `textEncoderThreshold` config properties.
+    These threshold were configurable via `textDecoderThreshold` and `textEncoderThreshold` config.
 
     This is not clear whether this configuration is worth to expose.
     Most of decoded and encoded strings are small.
     Fixed thresholds seem fair enough.
 
--   Assertions and development mode
+-   Add assertions and development mode
 
     Previously, bare-ts enabled a few assertions to check some function arguments.
     For instance, the following code could trigger an `AssertionError`:
@@ -71,51 +75,45 @@ This project adheres to [Semantic Versioning][semver].
 
 ## 0.3.0 (2022-04-25)
 
--   Full compliance to IEEE-754 (floating point numbers)
+-   BREAKING CHANGES: remove `readVoid` and `writeVoid`
 
-    NaN is now a valid value for f32 and f64.
+-   Full compliance to _IEEE-754_ (floating point numbers)
 
--   Remove {read,write}Void
+    `NaN` is now a valid value for f32 and f64.
 
--   Make @bare-ts/lib platform-agnostic
+-   Make _bare-ts/lib_ platform-agnostic
 
-    Use your favorite ESM-ready CDN and simply import @bare-ts/lib.
+    Use your favorite ESM-ready CDN and simply import `@bare-ts/lib`.
     This was made possible by removing the dependency over node:assert.
 
 ## 0.2.0 (2022-01-16)
 
--   Improve performance for reading and writing strings
+-   BREAKING CHANGES: rename all decode/encode into read/write
 
--   Improve performance for reading variable integers encoded on a single byte
-
--   Add a reader and a writer for fixed-strings
-
-    Users have now access to two new functions that enable to read and
-    write fixed-length strings.
+    `read` and `write` feel more low-level than `decode` and `encode`.
+    They are also more used among BARE implementations.
+    `decode` and `encode` are also used for high-level API such as `TextDEcoder` and `TextEncoder`.
 
     ```js
-    bare.readFixedString(bc, /* string's length in bytes */ 4)
-    bare.writeFixedString(bc, "bare")
-    ```
+    - bare.decodeU8(bc)
+    + bare.readU8(bc)
 
--   Simplification of ByteCursor
+    - bare.encodeU8(bc, 42)
+    + bare.writeU8(bc, 42)
+    ```
 
--   BREAKING CHANGE: rename all decode/encode into read/write
+-   BREAKING CHANGES: remove `ByteCursor#write`
 
-    read/write feel more low-level than decode/encode.
-    read/write are also more used among BARE implementations than decode/encode.
-    Moreover, in JS, decode and encode are used for high-level API such as
-    TextDEcoder and TextEncoder.
+    Use `writeU8FixedArray` instead:
 
-    ```js
-    bare.decodeU8(bc) // Previously
-    bare.readU8(bc) // Now
+    ```diff
+      const bc = new ByteCursor(buffer, config)
 
-    bare.encodeU8(bc, 42) // Previously
-    bare.writeU8(bc, 42) // Now
+    - bc.write(buffer)
+    + bare.writeU8FixedArray(bc, buffer)
     ```
 
--   BREAKING CHANGE: length can no longer be specified for fixed-array writers
+-   BREAKING CHANGES: length can no longer be specified for fixed-array writers
 
     Previously, you had to specify the length of the fixed-array to encode.
     If the given length was different of the actual array's length,
@@ -126,44 +124,46 @@ This project adheres to [Semantic Versioning][semver].
 
     Fixed-array writers now have the same signature as other writers.
 
-    ```js
-    bare.readerU8FixedArray(bc, Uint8Array.of(42, 24), 2) // Previously
-    bare.writeU8FixedArray(bc, Uint8Array.of(42, 24)) // Now
+    ```diff
+    - bare.readerU8FixedArray(bc, Uint8Array.of(42, 24), 2)
+    + bare.writeU8FixedArray(bc, Uint8Array.of(42, 24))
     ```
 
-    Note that fixed-array readers still require the specification of the
-    length:
+    Note that fixed-array readers still require the specification of the length:
 
     ```js
     bare.decodeU8FixedArray(bc, 2)
     ```
 
--   BREAKING CHANGE: ByteCursor no longer accept ArrayBuffer
+-   BREAKING CHANGES: `ByteCursor` no longer accept `ArrayBuffer`
 
-    ```js
-    new ByteCursor(new ArrayBuffer(5), config) // Now fails
-    new ByteCursor(new Uint8Array(5), config) // Update to this
+    ```diff
+    - new ByteCursor(new ArrayBuffer(5), config) // Now fails
+    + new ByteCursor(new Uint8Array(5), config) // Update to this
     ```
 
--   BREAKING CHANGE: remove `ByteCursor#write`
+-   Add a reader and a writer for fixed-strings
 
-    Use `writeU8FixedArray` instead:
+    Users have now access to two new functions that enable to read and
+    write fixed-length strings.
 
     ```js
-    const bc = new ByteCursor(buffer, config)
-
-    bc.write(buffer) // Previously
-    bare.writeU8FixedArray(bc, buffer) // Now
+    bare.readFixedString(bc, /* string's length in bytes */ 4)
+    bare.writeFixedString(bc, "bare")
     ```
 
+-   Improve performance for reading and writing strings
+
+-   Improve performance for reading variable integers encoded on a single byte
+
 ## 0.1.1 (2022-01-09)
 
--   Fix write offset when byteOffset > 0
+-   Fix write offset when `byteOffset` > 0
 
-    A ByteCursor may be instantiated with an array of bytes such that
-    the array's byteOffset is greater than 0.
-    The previous ByteCursor.write implementation did not take care of
-    adding this byteOffset to the ByteCursor's offset.
+    A `ByteCursor` may be instantiated with an array of bytes such that
+    the array's `byteOffset` is greater than 0.
+    The previous `ByteCursor#write` implementation did not take care of
+    adding this `byteOffset` to the `ByteCursor`'s offset.
 
     The following code no longer fail:
 
@@ -176,22 +176,25 @@ This project adheres to [Semantic Versioning][semver].
     assert.deepEqual(Array.from(bytes), [42, 24]) // Previously failed
     ```
 
--   Smaller CommonJS bundle
+-   Improve byte length computation of small string
 
--   Improve byte-length computation of small string
+-   Smaller CommonJS bundle
 
 ## 0.1.0 (2022-01-02)
 
--   `ByteCursor` abstraction to read and write safely a buffer of bytes
+-   Add decoders and encoders for basic types
+    (bool, opaque data, floats, integers, typed arrays, UTF-8 string)
+
+-   Add `ByteCursor` abstraction to read and write safely a buffer of bytes
 
--   Enable to configure at runtime:
+-   Add runtime configuration
 
     -   initial buffer length
+
     -   maximum buffer length
-    -   thresholds (string length) for switching from custom to native
-        UTF-8 decoders/encoders
 
--   Decoders and encoders for basic types
-    (bool, opaque data, floats, integers, typed arrays, UTF-8 string)
+    -   thresholds (string length) for switching from custom to native UTF-8 decoding and encoding
 
+[keep-changelog]: https://keepachangelog.com/en/1.0.0/
+[lib9-versionning]: https://github.com/lib9/guides/blob/main/lib9-versioning-style-guide.md#keep-a-changelog
 [semver]: https://semver.org/spec/v2.0.0.html