Skip to content

Commit 515e61e

Browse files
authored
docs: show decimal encoding evolution (#10007)
## Summary Addresses the [diagram feedback](#9947 (comment)) and [suggested before/after comparison](#9947 (comment)) from #9947. Shows how adding multi-child decimal support preserves the v1 wire contract while adding v2. ## Changes Separates the implementations before and after multi-child support, labels their read/write paths, and removes the unrelated footer details. Updates the example and caption to distinguish the implementation change from serialization. Signed-off-by: "Connor Tsui" <[email protected]>
1 parent 9e8abca commit 515e61e

2 files changed

Lines changed: 80 additions & 66 deletions

File tree

‎docs/_static/versioning-flow.svg‎

Lines changed: 70 additions & 58 deletions
Loading

‎docs/specs/versioning/design.md‎

Lines changed: 10 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -95,19 +95,21 @@ to the array structure, while still reading the same stored data under the same
9595

9696
## Example: decimal children
9797

98-
The decimal-byte-parts plugin can serialize the same in-memory array type using two wire formats.
99-
Its encoding stores decimal values in integer child arrays, either in one child or split across
100-
several children. The v1 wire contract permits only one child, while v2 adds support for multiple
101-
children under a distinct wire ID.[^decimal-availability]
98+
The decimal-byte-parts encoding initially stored each value in one signed integer child, so values
99+
had to fit in 64 bits. Adding up to three unsigned children extended the encoding to values that
100+
require 128 or 256 bits. The updated array type supports both single-child and multi-child arrays,
101+
while its plugin continues to read and write the v1 wire format. Arrays with multiple children use
102+
the additional v2 wire format.[^decimal-availability]
102103

103104
```{figure} ../../_static/versioning-flow.svg
104-
:alt: One decimal encoding holds either one signed child or a signed child with unsigned lower parts. The serializer chooses v1 for one child and v2 for multiple children. Both wire formats deserialize into the same array type.
105+
:alt: Before multi-child support, the decimal array held one signed child and read and wrote v1. After the change, the array supports one to four children and 128-bit and 256-bit values. Its plugin writes v1 for one child and v2 for multiple children, and reads both wire formats into the updated array type.
105106
:target: ../../_static/versioning-flow.svg
106107
:figclass: versioning-diagram
107108

108-
The arrows show the serializer's choices and the corresponding reads. Although v2 also accepts a
109-
single child, the serializer chooses v1 for that shape. Each child has its own wire ID because it is
110-
itself a serialized array.
109+
The rows compare the implementations before and after multi-child support was added. The vertical
110+
arrow marks that implementation change, while the horizontal arrows show writing and reading.
111+
Although v2 also accepts a single child, the serializer chooses v1 for that shape. Each child is
112+
itself a serialized array with its own wire ID.
111113
```
112114

113115
For a single-child array, the serializer reuses the child and writes v1 metadata without

0 commit comments

Comments
 (0)