github.com/ipld/go-ipld-prime@v0.21.0/CHANGELOG.md (about)

     1  CHANGELOG
     2  =========
     3  
     4  Here is collected some brief notes on major changes over time, sorted by tag in which they are first available.
     5  
     6  Of course for the "detailed changelog", you can always check the commit log!  But hopefully this summary _helps_.
     7  
     8  Note about version numbering: All release tags are in the "v0.${x}" range.  _We do not expect to make a v1 release._
     9  Nonetheless, this should not be taken as a statement that the library isn't _usable_ already.
    10  Much of this code is used in other libraries and products, and we do take some care about making changes.
    11  (If you're ever wondering about stability of a feature, ask -- or contribute more tests ;))
    12  
    13  - [Planned/Upcoming Changes](#planned-upcoming-changes)
    14  - [Released Changes Log](#released-changes)
    15  
    16  
    17  Planned/Upcoming Changes
    18  ------------------------
    19  
    20  Here are some outlines of changes we intend to make that affect the public API:
    21  
    22  - **IPLD Amend**: is likely to land soon; it implements a more efficient underlying architecture to support IPLD Patch and related features. IPLD Amend adds an interface to allow incremental changes to `Node`s in an efficient way. Whereas IPLD Patch is a protocol for expressing changes. We're still working on figuring out exactly where it fits in the stack and making sure it won't be disruptive but early benchmarks are very promising for both Patch and traversal-based transforms. See https://github.com/ipld/go-ipld-prime/pull/445 for more.
    23  - **Layered `Node` implementation optimizations**: When layering different implementations of `Node` builders or consumers, having to defer through basicnode types can lead to large inefficiencies of memory and speed. We are looking at ways to improve this situation, including ways to *assemble* layered assemblers. See https://github.com/ipld/go-ipld-prime/issues/443 for discussion and some initial plans.
    24  - **Selectors**: There have been some recurring wishes to do something about the Selector package layout.  There's no intended or prioritized date for this.  See https://github.com/ipld/go-ipld-prime/issues/236 for more.
    25  - **Absent / "Not found" values**: There may be some upcoming changes to exactly how "not found" values are handled in order to clarify and standardize the subject.  There's no finalized date for this.  See https://github.com/ipld/go-ipld-prime/issues/360 for more.
    26  
    27  Released Changes
    28  ----------------
    29  
    30  ### v0.21.0
    31  
    32  _2023 August 10_
    33  
    34  go-ipld-prime's release policy says that:
    35  
    36  > even numbers should be easy upgrades; odd numbers may change things
    37  
    38  This release is an odd number, and it does change some minor things.
    39  
    40  #### 🛠 Breaking
    41  
    42  * **Build**: The minimum version of Go has been bumped from 1.18 to **1.19**.
    43  * **Dependencies**: The go-cid dependency was upgraded from v0.3.2 to **v0.4.1**. This is a relatively minor change but the introduction of `ErrInvalidCid` wrapping may be breaking for some users.
    44  * **Selectors**: Remove hard error when a traversal encounters a slice matcher with a node that is not a string or bytes, by @rvagg [#529](https://github.com/ipld/go-ipld-prime/pull/529)
    45  
    46  #### 🔦 Features
    47  
    48  * **Traversal**: `Preloader` functionality, by @hannahhoward and @rvagg [#452](https://github.com/ipld/go-ipld-prime/pull/452)
    49    * See the [traversal](https://pkg.go.dev/github.com/ipld/go-ipld-prime/traversal) package documentation for more information on how a `Preloader` can be used to introduce parallelism into a traversal. The [Lassie](https://github.com/filecoin-project/lassie) project is currently using this functionality to speed up Bitswap block fetching; future releases of go-ipld-prime may include additional functionality being prototyped in Lassie to manage parallelism and caching.
    50  * **Schemas**: Support `listpairs` struct representation in DSL parsing, by @rvagg [#514](https://github.com/ipld/go-ipld-prime/pull/514)
    51  * **Schemas**: Support `inline` union representation in DSL parsing, by @rvagg [#527](https://github.com/ipld/go-ipld-prime/pull/527)
    52  * **Bindnode**: Support `listpairs` struct representation, by @rvagg [#514](https://github.com/ipld/go-ipld-prime/pull/514)
    53  * **Selectors**: Support negative values for slice matcher's `From` and `To`, by @rvagg [#530](https://github.com/ipld/go-ipld-prime/pull/530)
    54    * The slice matcher is currently being used to support byte-range fetching for the [IPFS Trustless Gateway](https://specs.ipfs.tech/http-gateways/trustless-gateway/) specification. Work is ongoing and can be seen in both the [Lassie](https://github.com/filecoin-project/lassie) and [Frisbii](https://github.com/filecoin-project/lassie) projects.
    55    * _Please note that this feature is currently considered **experimental** and shoule be used with care and with the expectation that it may change in the near future. Expect a release or two before this feature is considered stable._
    56  
    57  #### 🩹 Fixes
    58  
    59  * **Traversal**: `StartAtPath` work properly for matching walks, by @rvagg [#500](https://github.com/ipld/go-ipld-prime/pull/500)
    60  * **Traversal**: `WalkTransforming()` work properly, by @EdSchouten [#516](https://github.com/ipld/go-ipld-prime/pull/516)
    61  * **Basicnode**: `basic.NewInt()` returns a pointer like other constructors, by @hacdias [#525](https://github.com/ipld/go-ipld-prime/pull/525)
    62  * **Selectors**: Cache offsets for sequential reads in slice matcher, by @rvagg [#529](https://github.com/ipld/go-ipld-prime/pull/529)
    63  
    64  #### 🌟 Thanks!
    65  
    66  Thanks to @hacdias and @EdSchouten for their first contributions to go-ipld-prime!
    67  
    68  ### v0.20.0
    69  
    70  go-ipld-prime's release policy says that:
    71  
    72  > even numbers should be easy upgrades; odd numbers may change things
    73  
    74  As such, v0.20.0 is a relatively minor release with a grab-bag of small improvements and fixes.
    75  
    76  _2023 February 11_
    77  
    78  Schema errors can now [`errors.Is`](https://pkg.go.dev/errors#Is):
    79  
    80  * \[[`61c9ab10d4`](https://github.com/ipld/go-ipld-prime/commit/61c9ab10d4)] - **feat**: support errors.Is for schema errors (Ian Davis) [#476](https://github.com/ipld/go-ipld-prime/pull/476)
    81  
    82  Schema DMT (schema/dmt) is now more usable from the outside and has a new `ConcatenateSchemas` function that can be used to combine two schemas into one:
    83  
    84  * \[[`db9d8a7512`](https://github.com/ipld/go-ipld-prime/commit/db9d8a7512)] - Export schema/dmt.TypeSystem. (Eric Myhre) [#483](https://github.com/ipld/go-ipld-prime/pull/483)
    85  * \[[`39818c169a`](https://github.com/ipld/go-ipld-prime/commit/39818c169a)] - Add a SchemaConcatenate operation. (Eric Myhre) [#483](https://github.com/ipld/go-ipld-prime/pull/483)
    86  * \[[`c68ba53c67`](https://github.com/ipld/go-ipld-prime/commit/c68ba53c67)] - More accurate name for structure that contains easy access to prototypes. (Eric Myhre) [#483](https://github.com/ipld/go-ipld-prime/pull/483)
    87  * \[[`2ecabf1217`](https://github.com/ipld/go-ipld-prime/commit/2ecabf1217)] - Add several pieces of docs to schema/dmt. (Eric Myhre)
    88  * \[[`33475f0448`](https://github.com/ipld/go-ipld-prime/commit/33475f0448)] - Fix mispatched package declaration. (Eric Myhre)
    89  
    90  The DAG-CBOR codec now has an `DontParseBeyondEnd` option (default `false`) that allows it to parse undelimited streamed objects. This matches the same functionality already in DAG-JSON and should only be used for specialised cases:
    91  
    92  * \[[`7b00b1490f`](https://github.com/ipld/go-ipld-prime/commit/7b00b1490f)] - feat(dagcbor): mode to allow parsing undelimited streamed objects (Rod Vagg) [#490](https://github.com/ipld/go-ipld-prime/pull/490)
    93  
    94  `datamodel.Copy` got some direct test coverage and will now complain if you try to copy a `nil` node:
    95  
    96  * \[[`f4bb2daa27`](https://github.com/ipld/go-ipld-prime/commit/f4bb2daa27)] - fix(datamodel): add tests to Copy, make it complain on nil (Rod Vagg) [#491](https://github.com/ipld/go-ipld-prime/pull/491)
    97  
    98  The LinkSystem data loading check will compare links (CIDs) to ensure it loaded what you wanted; this now properly supports the case where your link is a pointer:
    99  
   100  * \[[`1fc56b8e7a`](https://github.com/ipld/go-ipld-prime/commit/1fc56b8e7a)] - Fix hash mismatch error on matching link pointer (Masih H. Derkani) [#480](https://github.com/ipld/go-ipld-prime/pull/480)
   101  
   102  ### v0.19.0
   103  
   104  _2022 October 13_
   105  
   106  go-ipld-prime's release policy says that:
   107  
   108  > even numbers should be easy upgrades; odd numbers may change things
   109  
   110  The major change in this release is a bump to Go 1.18.
   111  
   112  #### 🛠 Breaking Changes
   113  
   114  Update go.mod to Go 1.18.
   115  
   116  #### 🔦 Highlights
   117  
   118  * **Codecs**: [Correct JSON codec Bytes handling](https://github.com/ipld/go-ipld-prime/pull/472). This change does not impact DAG-JSON, which is the generally recommended codec for JSON output as the JSON codec cannot properly handle Bytes or Links.
   119  * **Dependencies**:
   120    * Update to go-multihash@v0.2.1: https://github.com/multiformats/go-multihash/releases/tag/v0.2.1
   121    * Update to go-multicodec@v0.6.0: https://github.com/multiformats/go-multicodec/releases/tag/v0.6.0
   122    * Update to go-cid@v0.3.2: https://github.com/ipfs/go-cid/compare/v0.2.0...v0.3.2
   123  
   124  ### v0.18.0
   125  
   126  _2022 August 01_
   127  
   128  go-ipld-prime's release policy says that:
   129  
   130  > even numbers should be easy upgrades; odd numbers may change things
   131  
   132  So, as an even number, this v0.18.0 release should be a smooth ride for upgraders from v0.17.0. We have 3 major feature additions, all focused on [Bindnode](https://pkg.go.dev/github.com/ipld/go-ipld-prime/node/bindnode).
   133  
   134  #### 🔦 Highlights
   135  
   136  * **Bindnode**: [Custom Go type converters](https://github.com/ipld/go-ipld-prime/pull/414) - Bindnode performs bidirectional mapping of Go types to the IPLD Data Model, and in doing so, it assumes a straightforward mapping of values to their encoded forms. But there are common cases where a Go type doesn't have a straightforward path to serialization, either because the encoded form needs a custom layout, or because bindnode doesn't have enough information to infer a serialization pattern. Custom Go type converters for bindnode allow a user to supply a pair of converter functions for a Go type that dictate how to map that type to an IPLD Data Model kind. See the **[bindnode documentation](https://pkg.go.dev/github.com/ipld/go-ipld-prime/node/bindnode)** for more information.
   137  * **Bindnode**: [Type registry](https://github.com/ipld/go-ipld-prime/pull/437) - Setting up Go type mappings with Bindnode involves some boilerplate. A basic type registry is now available that takes some of this boilerplate away; giving you a single place to register, and perform conversions to and from Go types, Data Model (`Node`) forms or directly through serialization. See the **[bindnode/registry documentation](https://pkg.go.dev/github.com/ipld/go-ipld-prime/node/bindnode/registry)** for more information.
   138  * **Bindnode** [Full `uint64` support](https://github.com/ipld/go-ipld-prime/pull/414/commits/87211682cb963ef1c98fa63909f67a8b02d1108c) - the `uint64` support introduced in go-ipld-prime@v0.17.0 has been wired into Bindnode. The Data Model (`Node`) forms expose integers as `int64` values, which is lossy for unsigned 64-bit integers. Bindnode Go types using `uint64` values are now lossless in round-trips through serialization to codecs that support the full range (DAG-CBOR most notably).
   139  
   140  You can see all of these new features in action using Filecoin Go types, allowing a mapping between Go types, Data Model (`Node`) forms, and their DAG-CBOR serialized forms with [data-transfer vouchers](https://github.com/filecoin-project/go-fil-markets/pull/713). These features also allow us to interact with the original Go types, without modification, including `big.Int` serialization to `Bytes`, Filecoin `Signature` serialization to a byte-prefix discriminated `Bytes` and more. Since the Go types are unchanged, they can also simultaneously support [cbor-gen](https://github.com/whyrusleeping/cbor-gen) serialization, allowing an easier migration path.
   141  
   142  ### v0.17.0
   143  
   144  _2022 Jun 15_
   145  
   146  go-ipld-prime's release policy says that:
   147  
   148  > even numbers should be easy upgrades; odd numbers may change things
   149  
   150  In that spirit, this v0.17.0 release includes some potentially breaking changes. Although minor, they are marked below and they may lead to behavioral changes in your use of this library.
   151  
   152  #### 🛠 Breaking Changes
   153  
   154  * **Codecs**:
   155    * DAG-CBOR, DAG-JSON: [Error on `cid.Undef` links in dag{json,cbor} encoding](https://github.com/ipld/go-ipld-prime/pull/433) - previously, encoding Link nodes that were empty CIDs (uninitialized zero-value or explicitly `cid.Undef`) would have passed through the DAG-CBOR or DAG-JSON codecs, silently producing erroneous output that wouldn't successfully pass back through a decode. (Rod Vagg)
   156  * **Bindnode**:
   157    * [Panic early if API has been passed ptr-to-ptr](https://github.com/ipld/go-ipld-prime/pull/427) - previous usage of bindnode using pointers-to-pointers may have deferred (or in some cases avoided) panics until deeper usage of the API, this change makes it earlier to make it clear that pointer-to-pointer is not appropriate usage. (Rod Vagg)
   158  * **Build**:
   159    * [Drop Go 1.16.x testing & begin testing Go 1.18.x](https://github.com/ipld/go-ipld-prime/pull/394) (Daniel Martí)
   160    * Note also that in this release, the [github.com/ipfs/**go-cid**](https://github.com/ipfs/go-cid) dependency is upgraded from 0.0.4 to 0.2.0 which includes a breaking change with the removal of the `cid.Codecs` and `cid.CodecToStr` maps which may disruptive. See [the go-cid@0.2.0 release page for details](https://github.com/ipfs/go-cid/releases/tag/v0.2.0).
   161  
   162  #### 🔦 Highlights
   163  
   164  * **Data Model**:
   165    * [Introduce `UIntNode` interface, used within DAG-CBOR codec to quietly support full uint64 range](https://github.com/ipld/go-ipld-prime/pull/413) (Rod Vagg)
   166  * **Bindnode**:
   167    * Fuzzing and hardening for production use (Daniel Martí)
   168    * Refuse to decode empty union values (Daniel Martí)
   169    * [Allow nilable types for IPLD `optional`/`nullable`](https://github.com/ipld/go-ipld-prime/pull/401) (Daniel Martí)
   170    * [More helpful error message for common enum value footgun](https://github.com/ipld/go-ipld-prime/pull/430) (Rod Vagg)
   171    * [Infer links and `Any` from Go types](https://github.com/ipld/go-ipld-prime/pull/432) (Rod Vagg)
   172  * **Schemas**:
   173    * DMT: Proper checking for unknown union members (Daniel Martí)
   174    * DMT: Enum representations must be valid members (Daniel Martí)
   175    * DMT: Reject duplicate or missing union representation members (Daniel Martí)
   176    * DSL: [Support `stringjoin` struct representation and `stringprefix` union representation](https://github.com/ipld/go-ipld-prime/pull/397) (Eric Evenchick)
   177    * DMT, DSL: [Enable inline types](https://github.com/ipld/go-ipld-prime/pull/404) (Rod Vagg)
   178  * **Patch**:
   179    * [Add initial version of IPLD Patch feature](https://github.com/ipld/go-ipld-prime/pull/350) (Eric Myhre) *(helped across the line by mauve and Rod Vagg)*
   180  * **Codecs**:
   181    * DAG-CBOR: [Reject extraneous content after valid (complete) CBOR object](https://github.com/ipld/go-ipld-prime/pull/386) (Rod Vagg)
   182    * DAG-CBOR: [add `DecodeOptions.ExperimentalDeterminism`](https://github.com/ipld/go-ipld-prime/pull/390) (currently only checking map sorting order) (Daniel Martí)
   183    * Printer: [Fix printing of floats](https://github.com/ipld/go-ipld-prime/pull/412) (Dustin Long)
   184    * DAG-JSON: [Add option to not parse beyond end of structure](https://github.com/ipld/go-ipld-prime/pull/435) (Petar Maymounkov)
   185  * **Build**:
   186    * Fix [macOS](https://github.com/ipld/go-ipld-prime/pull/400) and [Windows](https://github.com/ipld/go-ipld-prime/pull/405) testing (Rod Vagg)
   187    * [Fix 32-bit build support](https://github.com/ipld/go-ipld-prime/pull/407) (Rod Vagg)
   188    * [Make staticcheck and govet happy across codebase](https://github.com/ipld/go-ipld-prime/pull/406) (Rod Vagg)
   189    * Enable full [unified-ci](https://github.com/protocol/.github) GitHub Actions suite, including auto-updating (Rod Vagg)
   190    * [Enable dependabot, with monthly checks](https://github.com/ipld/go-ipld-prime/pull/417) (and update all dependencies) (Rod Vagg)
   191  
   192  Special thanks to **Daniel Martí** for many bindnode improvements and hardening, fuzzing across the library and improvements to the Schema DMT and DSL.
   193  
   194  ### v0.16.0
   195  
   196  _2022 March 09_
   197  
   198  - New: `traversal.WalkTransforming` is finally implemented!  (It's been a stub for quite a while.)  This works similarly to the other transform features, but can do more than change to the structure during a single walk.
   199  - New: Selectors support partial/ranged match on bytes or strings nodes.  (This is also a new feature for Selectors, recently specified.)
   200    [[#375](https://github.com/ipld/go-ipld-prime/pull/375); seealso specs in [ipld#184](https://github.com/ipld/ipld/pull/184)]
   201  - New: there's a `datamodel.LargeBytesNode` interface, which makes it possible to handle "large" blobs of bytes as a `Node`, without necessarily forcing them all into memory at once.  (This is optional; you add the methods to match the interface if your Node implementation supports the feature.)
   202    [[#372](https://github.com/ipld/go-ipld-prime/pull/372)]
   203  	- Slightly more specifically: this interface is `Node` plus a method that returns an `io.ReadSeeker`.  (Pretty standard golang I/O and byte slice management concepts should carry you from there in the usual ways.)
   204  	- This is a **really big deal** -- for example, this means that an [ADL](https://ipld.io/docs/advanced-data-layouts/) can support reading of arbitrarily large bytes without an issue.  (Hello, transparently readable large sharded blobs!)
   205  - New: there's a "resume" (or, skipahead) mechanism for traversals and selectors.  Engage it by simply setting the `traversal.Config.StartAtPath` field.
   206    [[#358](https://github.com/ipld/go-ipld-prime/pull/358)]
   207  - New: `dagcbor` now has a `EncodedLength(Node) int` function, which can calculate the expected serial message length without actually encoding.  (The usefulness of this may be situational, but it's there if you want it.)
   208  - Improved: `bindnode`, yet again, in more ways that can easily be summarized.
   209  	- Better support for pointers in more places in your golang types.
   210  	- Many panics either fixed or routed into calmer errors.
   211  	- Unsigned intergers are now supported in your golang types.
   212  	- Some fixes for AssignNode working correctly (e.g. at the type or representation level, as appropriate; sometimes previously it would use the type level incorrectly).
   213  	- Various fixes to handling absent fields correctly.
   214  	- A `datamodel.Node` can now be used for an `any` field.
   215  - Fixed: selectors now behave correctly for a recursion clause that just contains a recursion edge immedately.  (It's still not a sensible selector, really, but it's valid.)  Previously this would panic, which was nasty.
   216  - Fixed: `bindnode` now correctly doesn't include absent fields in the count of length when looking at the representation-level view of structs.
   217  - Improved: all our batteries-included codecs double check while encoding that the number iterator steps over a map matches its self-reported length.  (This doesn't matter in many cases, but does defend you a little better against a `Node` implementation with a bug, if you happen to be so unlucky.)
   218  - Improved: miscellaneous performance work in the `schema/*` area.
   219  
   220  Thank you to @mvdan, @warpfork, @hannahhoward, @rvagg, @willscott, @arajasek and others
   221  for all their work that went into making this release (as well as all the point releases in v0.14.x leading up to it) happen.
   222  
   223  Finally, please note that we're starting to try out some new (and slightly more formal) governance and review and merge processes.
   224  Check out https://github.com/ipld/go-ipld-prime/issues/370 for more information.
   225  The aim is to make things generally more inclusive and involve more contributors!
   226  This is still experimental and may be subject to change, but if you'd like to have better expectations about who can review and what the process should be like, we hope this will be a step in a helpful direction.
   227  (Feedback about this experiment welcome!)
   228  
   229  
   230  ### v0.14.x
   231  
   232  (There were releases `v0.14.1`, `v0.14.2`, `v0.14.3`, and `v0.14.4` -- but all were in rapid succession, very minor, and hitting the same areas; we'll keep the notes brief and condensed.)
   233  
   234  - New: Selectors can include clauses for signalling the use of ADLs!
   235    [[#301](https://github.com/ipld/go-ipld-prime/pull/301); seealso specs in [ipld#149](https://github.com/ipld/ipld/pull/149)+[ipld#170](https://github.com/ipld/ipld/pull/170)]
   236  	- Also kindly note that there are expected to be many ways of signalling ADL invocations -- this is only one of them.
   237  	  See the IPLD website for more on this topic as a whole: https://ipld.io/docs/advanced-data-layouts/signalling/
   238  - Improved: `bindnode`, in ways more various than can easily be summarized.
   239  	- The `cidlink.Link` type can be bound to links in the data.
   240  	- Enums are now supported.
   241  	- The `any` typekind is now supported.
   242  - Improved: both the `schema/dmt` and `schema/dsl` packages (and in some cases, the `schema` package itself) continue to be improved and become more complete.
   243  	- Structs with tuple representation are now supported.
   244  	- Enums with int representation are now supported.
   245  	- The `any` typekind is now supported.
   246  - Changed: the dag-json codec will tolerate padded base64 in bytes content upon read.  It does so silently.  (It is not still possible to emit this kind of serial data with this library; it is noncanonical.)
   247    [[#309](https://github.com/ipld/go-ipld-prime/pull/309)]
   248  - Changed: the cbor and dag-cbor codec will now tolerate CBOR's "undef" token.  It will coerce it to a null token when reading.  Previously, encountering the undef token would result in a parse error.  (It is still not possible to emit this token with this library.)
   249    [[#308](https://github.com/ipld/go-ipld-prime/pull/308)]
   250  - New: the `traversal` package gained a `WalkLocal` function.  This simply does a walk that does not cross any links.
   251  
   252  
   253  ### v0.14.0
   254  
   255  _2021 November 11_
   256  
   257  This release is a smooth-sailing release, and mostly contains new features, quality-of-life improvements,
   258  and some significant improvements to the completeness and usability of features that have been in development across previous releases.
   259  There shouldn't be a lot of surprises, and upgrading should be easy.
   260  
   261  Some of the biggest improvements include: `bindnode` now supports most IPLD features and is increasingly stable;
   262  the `schema` system now has functioning `schema/dmt` and `schema/dsl` packages, and can parse schema documents smoothly(!);
   263  if you haven't seen the `printer` package that first quietly appeared in `v0.12.2`, you should definitely check it out now;
   264  and we have some new `storage` APIs that might be worth checking out, too.
   265  There are also many, many other smaller improvements.
   266  
   267  See the complete list and further deatils below
   268  (and don't forget to check out the notes under the other `v0.12.*` headings, if you haven't absorbed those updates already, too!):
   269  
   270  - New: `datamodel.Copy`: a helper function to do a shallow copy from one node to another.
   271  	- You don't often need this, because nodes are supposed to be immutable!
   272  	  But it still sometimes comes in handy, for example, if you want to change the memory layout you're using by moving data into a different node implementation.
   273  - Improved: documentation of APIs.  (Especially, for subtler bits like `NodeAssembler.AssignNode`.)
   274  - New: `datamodel.Link` now requires a `Binary()` function.  In contrast to `Link.String()` (which is supposed to return something printable), `Link.Binary()` should give you the rawest thing possible.  (It's equivalent to `go-cid.CID.KeyString`.)
   275  - New: **a new storage API**, including one **batteries-included** filesystem storage implementation, and **adapters** to several other different storage APIs.  [[#265](https://github.com/ipld/go-ipld-prime/pull/265), [#279](https://github.com/ipld/go-ipld-prime/pull/279)]
   276  	- The primary goal of this is the "batteries included" part: using the new `storage/fsstore` package, you should now be able to make simple applications with IPLD and use a simple sharded disk storage system (it'll look vaguely like a `.git/objects` directory), and do it in about five minutes and without pulling in any additional complex dependencies.
   277  	- If you want to develop new storage systems or make adapters to them: the APIs in `storage` package are designed to be implemented easily.
   278  		- The `storage` APIs are designed entirely around types found in the golang standard library.  You do not need to import anything in the `storage` package in order to implement its interfaces!
   279  		- The minimal APIs that a storage system has to implement are _very_ small.  Two functions.  Every additional feature, or optimization that you can offer: those all have their own interfaces, and we use feature-detection on them.  You can implement as much or as little as you like.
   280  	- As a user of the storage APIs: use the functions in the `storage` package.  Those functions take a storage system as a parameter, and will do feature detection _for you_.
   281  		- This means you can always write your code to call the APIs you _want_, and the `storage` functions will figure out how to map it onto the storage system that you _have_ (whatever it supports) in the most efficient way it can.
   282  	- As a user of the `LinkSystem` API: you can ignore most of this!  If you want to use the new `storage` APIs, there are setup methods on `LinkSystem` that will take them as a parameter.  If you have existing code wired up with the previous APIs, it still works too.
   283  	- As someone who already has code and wonders how to migrate:
   284  		- If you're using the `linking.Storage*Opener` API: you don't have to do anything.  Those still work too.
   285  		- If you were using code from other repos like `ipfs/go-ipfs-blockstore` or `ipfs/go-datastore` or so on: those have adapters now in the `storage/*adapter` packages!  You should now be able to use those more easily, with less custom glue code.  (There's also now a migration readme in the repo root: check that out.)
   286  	- If you would like to ask: "is it fast?" -- yes.  You'll find that the new `storage/fsstore`, our batteries-included filesystem storage system, is comparable (or beating) the `go-ds-flatfs` package that you may have been using in the past.  (More benchmarks and any performance improvement patches will of course be welcome -- but at the very least, there's no reason to hold back on using the new system.)
   287  - New: `LinkSystem` has some new methods: `LoadRaw` and `LoadPlusRaw` give you the ability to get data model nodes loaded, and _also_ receive the raw binary blobs.
   288  	- This can be useful if you're building an application that's piping data around to other serial APIs without necessarily transforming it.  (No need to reserialize if that's your journey.)
   289  - New: a CLI tool has begun development!
   290  	- ... and almost immediately been removed again, to live in its own repo: check out https://github.com/ipld/go-ipldtool .
   291  - Improved: many more things about `bindnode`.
   292  	- `bindnode` now understands `go-cid.CID` fields.
   293  	- Kinded unions are much more completely supported.
   294  	- Many TODO panics have gone away, replaced by finished features.
   295  	- `bindnode` will increasingly check that the golang types you give it can be structurally matched to the schema if you provide one, which gives better errors earlier, and increases the ease and safety of use drastically.
   296  - Improved: the `schema/dmt` and `schema/dsl` packages are increasingly complete.
   297  	- There are also now helper functions in the root package which will do the whole journey of "load a file, parse the Schema DSL, compile and typecheck the DMT, and give you the type info in handy golang interfaces", all at once!  Check out `ipld.LoadSchema`!
   298  - New: there is a codegen feature for `bindnode` which will produce very terse golang structs matching a schema and ready to be bound back to `bindnode`!
   299  	- This competes with the older `gengo` code generator -- by comparison, the `bindnode` code generator produces much, _much_ less code.  (However, be advised that the performance characteristics are probably also markedly different; and we do not have sufficient benchmarks to comment on this at this time.)
   300  - Internal: many tests are being ported to `quicktest`.  There should be no external impact to this, but we look forward to removing some of the other test libraries from our dependency tree in the near future.
   301  - Improved: `printer` now supports links and bytes!
   302  - Improved: `printer` is now more resilient and works even on relatively misbehaved `Node` implementations, such as those which implement `schema.TypedNode` but then rudely and nonsensically return nil type info.  (We don't expect all code to be resilient against misbehaved `Node` implementations... but for a debug tool in particular?  It's good to have it handle as much as it can.)
   303  
   304  
   305  This, and the last few releases tagged in the `v0.12.*` series, include invaluable contributions from
   306  @mvdan, @warpfork, @rvagg, @willscott, @masih, @hannahhoward, @aschmahmann, @ribasushi,
   307  and probably yet more others who have contributed through code and design reviews,
   308  or by using these libraries and demanding they continue to become better.
   309  Thanks to each and every one of the people who carry this project forward!
   310  
   311  
   312  ### v0.12.3
   313  
   314  _2021 September 30_
   315  
   316  (This is a minor release; we'll keep the notes brief.)
   317  
   318  - Fixed: using `SkipMe` in a traversal now skips only that subtree of nodes, not the remainder of the block!
   319    [[#251](https://github.com/ipld/go-ipld-prime/pull/251)]
   320  - New: `traversal` features now have budgets!  You can set a "budget" value, and watch it monotonically decrement as your operations procede.  This makes it easy to put limits on the amount of work you'll do.
   321    [[#260](https://github.com/ipld/go-ipld-prime/pull/260)]
   322  - New: `traversal` features can be configured to visit links they encounter only once (and ignore them if seen again).
   323    [[#252](https://github.com/ipld/go-ipld-prime/pull/252)]
   324  	- Note that this is not without caveats: this is not merely an optimization; enabling it _may_ produce logically different outcomes, depending on what your selector is.
   325  	  This is because links are ignored when seen again, even if they're seen for a different _reason_, via a different path, etc.
   326  - Fixed: a very nasty off-by-one in unions produced by the "gogen" codegen.
   327    [[#257](https://github.com/ipld/go-ipld-prime/pull/257)]
   328  - Improved: the test suites for typed nodes now provide much better coverage (to prevent something like the above from happening again, even in other implementations).
   329  - New: `schema/dsl`!  This package contains parsers for the IPLD Schema DSL, and produces data structures in `schema/dmt` form.
   330  - Removed: other misc partially-complete packages.  (This will surely bother no one; it's just cleanup.)
   331  - Removed: `codec/jst`.  If you were using that, [`jst` has its own repo](https://github.com/warpfork/go-jst/) now.
   332  - Improved: `traversal` now uses the error wrapping ("`%w`") feature in more places.
   333  - Changed: `printer` keeps empty maps and lists and strings on a single line.
   334  - Changed: `schema.TypeName` is now just an alias of `string`.  This may result in somewhat less casting; or, you might not notice it.
   335  - Improved: the `schema/dmt` package continues to be improved and become more complete.
   336  	- Some changes also track fixes in the schema spec, upstream.  (Or caused those fixes!)
   337  - New/Improved: the `schema` package describes several more things which it always should have.  Enums, for example.
   338  
   339  
   340  
   341  ### v0.12.2
   342  
   343  _2021 September 8_
   344  
   345  (This is a minor release; we'll keep the notes brief.)
   346  
   347  - New: the `printer` package has appeared, and aims to provide an information-rich, debug-readable, human-friendly output of data from an IPLD node tree. [[#238](https://github.com/ipld/go-ipld-prime/pull/238/)]
   348  	- This works for both plain data model data, and for typed data, and annotates type information if present.
   349  	- Note that this is _not_ a codec: it's specifically _richer_ than that.  Conversely, this printer format is not designed to be parsed back to data model data.  Use a codec for a codec's job; use the printer for debugging and inspection jobs.
   350  - Fixed/Improved: more things about the `bindnode` system.  (It's still early and improving fast.)
   351  - Fixed: json codec, cbor codec, and their dag variants all now return ErrUnexpectedEOF in the conditions you'd expect.  (Previously they sometimes just returned EOF, which could be surprising.)
   352  - Changed/Improved: the `schema/dmt` package is now implemented using `bindnode`, and there's a more complete `Compile()` feature.  (This is still very early, in this tag.  More to come here soon.)
   353  
   354  
   355  
   356  ### v0.12.1
   357  
   358  _2021 August 30_
   359  
   360  (This is a minor release; we'll keep the notes brief.)
   361  
   362  - Fixed/Improved: many things about the `bindnode` system.  (It's still early and improving fast.)
   363  - Changed: the strings for `schema.TypeKind_*` are lowercase.  (The docs and specs all act this way, and always have; it was a strange error for this code to have titlecase.)
   364  - New: the root package contains more helper methods for encoding and decoding operations
   365  
   366  
   367  
   368  ### v0.12.0
   369  
   370  _2021 August 19_
   371  
   372  This release is a momentous one.  It contains a sizable refactor:
   373  we've extracted some of the most key interfaces to a new package, called `datamodel`!
   374  
   375  It's also an even numbered release tag, which we generally use to indicate "upgrading should be smooth sailing".
   376  Surprisingly, despite the magnitude of the refactor, we mean that, too.
   377  Golang's "alias" feature has been used _heavily_ for this change process,
   378  and downstream code that worked on the previous release should continue to work on this release too, without syntactic changes.
   379  
   380  Why did we do this?
   381  
   382  The root package, `ipld`, is now going to be a place where we can put helpful functions.
   383  Synthesis functions that put all the pieces of IPLD together for you.
   384  The functions you're probably looking for; the high-level stuff that gets work done.
   385  
   386  Previously, the root package was _guts_: the lowest level interfaces, the more core stuff...
   387  which was cool to see (arguably), but tended not to be the things you'd want to see _first_ as a new user.
   388  And because everything _else_ in the world depended on those interface,
   389  we could never put interesting high-level functions in the same package
   390  (or if we tried, compilation would fail, because of import cycles)...
   391  which meant any time we wanted to add helper functions for getting useful work done,
   392  we'd be stuck cramming them off into subpackages somewhere.
   393  While this worked, the discoverability for a new user was terribly arduous.
   394  
   395  We hope this pivot to how we organize the code helps you find your way through IPLD!
   396  
   397  We haven't yet added many of the new helper features to the updated root package.
   398  Those will come in the very near future.
   399  (Follow along with commits on the master branch if you want to try the new APIs early!)
   400  This release is being made just to cover the refactor, before we steam along any further.
   401  
   402  Your existing code should continue working without changes because the root `ipld` package
   403  still contains all the same types -- just as aliases.
   404  You can choose to update your code to use the types where they've moved to
   405  (which is mostly the `datamodel` package), or, if you prefer... just leave it as-is.
   406  Some aliases may be removed over time; if so, they'll be marked with a comment to that effect,
   407  and there should be plenty of warning and time to change.
   408  
   409  In some cases, continuing to use the `ipld` package directly will remain acceptable indefinitely.
   410  The new intention is that common work should often be possible to do only by
   411  importing the `ipld` package, and users should only need to dive into
   412  the more specific subpackages if they been to need direct access to more detailed APIs
   413  for performance or other reasons.
   414  
   415  That's it for the big refactor news.
   416  
   417  There's also some sweet new features in bindnode,
   418  and a few other important fixes to recently introduced features.
   419  
   420  In detail:
   421  
   422  - Changed: that massive refactor, described above.  Gosh it's big.
   423    [[#228](https://github.com/ipld/go-ipld-prime/pull/228)]
   424  - New: the selectors system is tested against the language-agnostic selector specs, from the IPLD specs+docs repo!
   425    [[#231](https://github.com/ipld/go-ipld-prime/pull/231)]
   426  	- This uses a new fixture format, called [testmark](https://github.com/warpfork/go-testmark#what-is-the-testmark-format), which is managed by a library called [go-testmark](https://pkg.go.dev/github.com/warpfork/go-testmark).
   427  	- The fixtures are drawn in by a git submodule.  The actual fixture content remains in the [ipld/ipld](https://github.com/ipld/ipld/) repo.
   428  	- These new tests will be run if you have cloned the git submodule (and of course, by CI).  If you do not clone the submodule that contains the fixtures, the tests will quietly skip.
   429  	- We hope this will be a template for how to do more testing in the future, while keeping it closely coordinated with specs, and in sync with other implementations of IPLD in other languages!
   430  - Improved: bindnode: in a variety of ways.
   431    [[#226](https://github.com/ipld/go-ipld-prime/pull/226)]
   432  	- Several error messages are improved.
   433  	- Kinded unions support complex recipients even for string kinds.  (E.g., putting a struct with stringjoin representation inside a kinded union now works correctly.)
   434  	- Stringprefix unions now work even with no explicit delimiter.
   435  	- Please note that bindnode is, and remains, considered experimental.  While we're improving it, it's still something to use at your own risk.
   436  - Changed/Improved: bindnode: unions are now handled completely differently (and much better).
   437    [[#223](https://github.com/ipld/go-ipld-prime/pull/223)]
   438  	- In short: now they expect a golang struct which has a field for each of the possible members, and each of them should be a pointer.  This is type safe and works reasonably idiomatically in golang.
   439  	- This is a fairly huge improvement, because it fixes the "bindnode unions force downshift into anonymous types" problem, which was tracked as [issue#210](https://github.com/ipld/go-ipld-prime/issues/210).
   440  - Fixed: the selector `ExploreRecursive.stopAt` feature now actually... works.  It was completely broken when it was introduced in the last release.  (Tests.  They're important.)
   441    [[#229](https://github.com/ipld/go-ipld-prime/pull/229)]
   442  	- Notice how we've also now got selector tests driven by fixtures appearing in this release.  Hopefully that decreases the odds of something like this happening again.
   443  
   444  
   445  
   446  ### v0.11.0
   447  
   448  _2021 August 12_
   449  
   450  This release is an odd numbered release, which means it may contain breaking changes.
   451  
   452  Unfortunately, the changes here may be particularly, tricky, as well -- for the most part, they're not compile-time detectable.
   453  They're behavioral changes.  Much more subtle.  Run tests on your systems before accepting these changes.
   454  Specifically: several codecs now enforce sorting when emitting serial data.
   455  
   456  There's also some details of what's changing that makes it milder than it first sounds:
   457  most of the changes are around codecs becoming *more* spec-compliant.
   458  So, for example, if you were using another IPLD library that always enforced sorting on e.g. DAG-CBOR,
   459  you won't be surprised or experience it much like a "change" when using this version of go-ipld-prime, which now also enforces such sorting in that codec.
   460  
   461  Also!  At least one huge and awesome new feature: `bindnode`.
   462  This is a new implementation of `ipld.Node` which can bind to native golang structures using reflection,
   463  which provides a new and easy-to-use way to move data in and out of golang structures (or traverse them, etc!) with IPLD interfaces and codecs.
   464  
   465  See the full change list for details:
   466  
   467  - New: some new helpful constructors for making Selectors out of serial forms can now be found in the `traversal/selector/parse` package.
   468    [[#199](https://github.com/ipld/go-ipld-prime/pull/199)]
   469  	- Some constants are also included which show some examples of creating common selectors from JSON.
   470  - Fixed: cbor, dag-cbor, json, and dag-json codecs now all accept parsing a block that contains just a null token alone.  (Previously, this returned an "unexpected EOF" error, which was silly.)
   471    [[#217](https://github.com/ipld/go-ipld-prime/pull/217)]
   472  - Fixed (upstream): json floats are actually supported.  (You might've had this already, if anything dragged in a newer version of the `refmt` library.  We just make sure to require this ourselves in our `go.mod` file now.)
   473    [[#215](https://github.com/ipld/go-ipld-prime/pull/215)]
   474  - New: Selectors now support some kinds of conditions.  Specifically, `ExploreRecursive` clauses can contain a `stopAt` condition, and the condition system now supports `Condition_IsLink`, which can be used to do an equality check for CIDs.
   475    [[#214](https://github.com/ipld/go-ipld-prime/pull/214)]
   476  - Fixed: in codegen'd types, the `LinkTargetNodePrototype` on links was returning the wrong prototype; now it returns the right one.
   477    [[#211](https://github.com/ipld/go-ipld-prime/pull/211)]
   478  - New: `schema.TypedPrototype` interface, which is like `ipld.NodePrototype` but also has methods for asking `Type() schema.Type` and `Representation() ipld.NodePrototype`, both of which should probably instantly make sense to you.
   479    [[#195](https://github.com/ipld/go-ipld-prime/pull/195)]
   480  - Changed: the dag-json and dag-cbor codecs now apply sorting.
   481    [[#203](https://github.com/ipld/go-ipld-prime/pull/203), [#204](https://github.com/ipld/go-ipld-prime/pull/204)]
   482  	- This means all serial data created with these codecs is sorted as advised by their respective specifications.
   483  	  Previously, the implementations of these codecs was order-preserving, and emitted data in whatever order the `ipld.Node` yielded it.
   484  	- There may be new performance costs originating from this sorting.
   485  	- The codecs do not reject other orderings when parsing serial data.
   486  	  The `ipld.Node` trees resulting from deserialization will still preserve the serialized order.
   487  	  However, it has now become impossible to re-encode data in that same preserved order.
   488  	- If doing your own encoding, there are customization options in `dagcbor.EncodeOptions.MapSortMode` and `dagjson.EncodeOptions.MapSortMode`.
   489  	  (However, note that these options are not available to you while using any systems that only operate in terms of multicodec codes.)
   490  	- _Be cautious of this change._  It is now extremely easy to write code which puts data into an `ipld.Node` in memory in one order,
   491  	  then save and load that data using these codecs, and end up with different data as a result because the sorting changes the order of data.
   492  	  For some applications, this may not be a problem; for others, it may be surprising.
   493  	  In particular, mind this carefully in the presense of other order-sensitive logic -- for example,
   494  	  such as when using Selectors, whose behaviors also depend on ordering of data returned when iterating over an `ipld.Node`.
   495  - Fixed/Changed: the dag-json codec no longer emits whitespace (!).  It is now spec-compliant.
   496    [[#202](https://github.com/ipld/go-ipld-prime/pull/202)]
   497  	- This means hashes of content produced by dag-json codec will change.  This is unfortunate, but the previous implementation was woefully and wildly out of sync with the spec, and addressing that is a predominating concern.
   498  - Removed: `fluent/quip` has been dropped.  `fluent/qp` is superior.  `fluent/quip` was too easy to use incorrectly, so we no longer offer it.
   499    [[#197](https://github.com/ipld/go-ipld-prime/pull/197)]
   500  	- This was an experimental package introduced a few releases ago, together with caveats that we may choose to drop it.  The warning was purposeful!
   501  	  We don't believe that this will be too painful of a change; not many things depended on the `fluent/quip` variant, and those that did should not be difficult to rewrite to `fluent/qp`.
   502  - New: `node/basic.Chooser` is a function that implements `traversal.LinkTargetNodePrototypeChooser`.  It's a small handy quality-of-life increase if you need to supply such a function, which is common.
   503    [[#198](https://github.com/ipld/go-ipld-prime/pull/198)]
   504  - New: `bindnode`!  **This is a huge feature.**  The beginnings of it may have been visible in v0.10.0, but it's grown into a usable thing we're ready to talk about.
   505  	- Bindnode lets you write golang types and structures, and "bind" them into being IPLD Nodes and supporting Data Model operations by using golang reflection.
   506  	- The result of working with `bindnode` is somewhere between using basicnode and using codegen:
   507  	  it's going to provide some structural constraints (like codegen) and provide moderate performance (it lets you use structs rather than memory-expensive maps; but reflection is still going to be slower than codegen).
   508  	- However, most importantly, `bindnode` is *nice to use*.  It doesn't have a huge barrier to entry like codegen does.
   509  	- `bindnode` can be used with _or without_ IPLD Schemas.  For basic golang types, a schema can be inferred automatically.  For more advanced features (e.g. any representation customization), you can provide a Schema.
   510  	- Please note that though it is now usable, bindnode remains _in development_.  There is not yet any promise that it will be frozen against changes.
   511  		- In fact, several changes are expected; in particular, be advised there is some sizable change expected around the shape of golang types expected for unions.
   512  - Improved: tests for behavior of schema typed nodes are now extracted to a package, where they are reusable.
   513  	- The same tests now cover the `bindnode` implementation, as well as being used in tests of our codegen outputs.
   514  	- Previously, these tests were already mostly agnostic of implementation, but had been thrown into packages in a way that made them hard to reuse.
   515  - Improved (or Fixed, depending on your point of view): dag-json codec now supports bytes as per the spec.
   516    [[#166](https://github.com/ipld/go-ipld-prime/pull/166),[#216](https://github.com/ipld/go-ipld-prime/pull/216)]
   517  	- Bytes are encoded in roughly this form: `{"/":{"bytes":"base64data"}}`.
   518  	- Note: the json codec does _not_ include this behavior; this is behavior specific to dag-json.
   519  
   520  
   521  
   522  ### v0.10.0
   523  
   524  _2021 June 02_
   525  
   526  v0.10.0 is a mild release, containing _no_ breaking changes, but lots of cool new stuff.  Update at your earliest convenience.
   527  
   528  There's a bunch of cool new features in here, some of which are significant power-ups for the ecosystem (e.g. the `NodeReifier` API), so we recommend updating as soon as possible.
   529  
   530  There's also some sizable performance improvements available for generated code, so go forth and update your generated code too!
   531  
   532  Check out the full feature list:
   533  
   534  - New: an `ipld.DeepEqual` method lets you easily compare two `ipld.Node` for equality.  (This is useful in case you have nodes with two different internal implementations, different memory layouts, etc, such that native golang equality would not be semantically correct.)
   535    [[#174](https://github.com/ipld/go-ipld-prime/pull/174)]
   536  - New: the multicodec package exposes a `multicodec.Registry` type, and also some `multicodec.List*` methods.
   537    [[#172](https://github.com/ipld/go-ipld-prime/pull/172), [#176](https://github.com/ipld/go-ipld-prime/pull/176)]
   538  	- Please be cautious of using these `List*` methods.  It's very possible to create race conditions with these, especially if using them on the global default registry instance.
   539  	  If we detect that these access methods seem to produce a source of bugs and design errors in downstream usage, they will be removed.
   540  	  Consider doing whatever you're doing by buildling your own registry systems, and attaching whatever semantics your system desires to those systems, rather than shoehorning this intentionally limited system into doing things it isn't made to do.
   541  - Improved: the dag-json codec now actually supports bytes!
   542    (Perhaps surprisingly, this was a relatively recent addition to the dag-json spec.  We've now caught up with it.)
   543    [[#166](https://github.com/ipld/go-ipld-prime/pull/166)]
   544  - Improved: the codegen system now gofmt's the generated code immediately.  You no longer need to do this manually in a separate step.
   545    [[#163](https://github.com/ipld/go-ipld-prime/pull/163)]
   546  - Improved: the codegen system is slightly faster at emitting code (due to use of more buffering during writes).
   547    [[#161](https://github.com/ipld/go-ipld-prime/pull/161)]
   548  - Improved: the codegen system will now avoid pointers in the generated "Maybe" types, if they're known to be small in memory (and thus, reasonable to inline).
   549    [[#160](https://github.com/ipld/go-ipld-prime/pull/160)]
   550  	- This is quite likely to result in performance improvements for most programs, as it decreases the number of small memory allocations done, and amount of time spent on dereferencing, cache misses, etc.
   551  	  Some workloads demonstrated over 10% speed increases, and 40% decreases in allocation counts.
   552  	  (Of course, run your own benchmarks; not all workloads are equal.)
   553  - New: `ipld.LinkSystem` now contains a "reification" hook system.  **This is really cool.**
   554  	- The center of this is the `ipld.LinkSystem.NodeReifier` field, and the `ipld.NodeReifier` function type.
   555  	- The `ipld.NodeReifier` function type is simply `func(LinkContext, Node, *LinkSystem) (Node, error)`.
   556  	- The purpose and intention of this is: you can use this hooking point in order to decide where to engage advanced IPLD features like [ADLs](https://ipld.io/glossary/#adl).
   557  	  One can use a `NodeReifier` to decide what ADLs to use and when... even when in the middle of a traversal.
   558  	- For example: one could write a NodeReifier that says "when I'm in a path that ends with '`foosys/*/hamt`', i'm going to try to load that as if it's a HAMT ADL".
   559  	  With that hook in place, you'd then be able to walks over whole forests of data with `traversal.*` functions, and they would automatically load the relevant ADL for you transparently every time that pattern is encountered, without disrupting or complicating the walk.
   560  	- In the future, we might begin to offer more structural and declaratively configurable approaches to this, and eventually, attempt to standardize them.
   561  	  For now: you can build any solution you like using this hook system.  (And we'll probably plug in any future declarative systems via these same hooks, too.)
   562  	- All this appeared in [#158](https://github.com/ipld/go-ipld-prime/pull/158).
   563  - New: `ipld.LinkSystem` now contains a boolean flag for `TrustedStorage`.  If set to true, it will cause methods like `Load` to _skip hashing_ when loading content.  **_Do not do this unless you know what you're doing._**
   564    [[#149](https://github.com/ipld/go-ipld-prime/pull/149)]
   565  - New: a json (as opposed to dag-json) codec is now available from this repo.  It does roughly what you'd expect.  (It's like dag-json, but explicitly rejects encoding links and bytes, and correspondingly does not have dag-json's special decoding behaviors that produce those kinds.)
   566    [[#152](https://github.com/ipld/go-ipld-prime/pull/152)]
   567  - New: a cbor (as opposed to dag-cbor) codec is now available from this repo.  Same story as the json codec: it just explicitly doesn't support links (because you should use dag-cbor if you want that).
   568    [[#153](https://github.com/ipld/go-ipld-prime/pull/153)]
   569  
   570  This contained a ton of contributions from lots of people: especially thanks to @mvdan, @hannahhoward, and @willscott for invaluable contributions.
   571  
   572  
   573  
   574  ### v0.9.0
   575  
   576  _2021 March 15_
   577  
   578  v0.9.0 is a pretty significant release, including several neat new convenience features, but most noticeably, significantly reworking how linking works.
   579  
   580  Almost any code that deals with storing and linking data will need some adaptation to handle this release.
   581  We're sorry about the effort this may require, but it should be worth it.
   582  The new LinkSystem API should let us introduce a lot more convenience features in the future, and do so *without* pushing additional breakage out to downstream users; this is an investment in the future.
   583  
   584  The bullet points below contain all the fun details.
   585  
   586  Note that a v0.8.0 release version has been skipped.
   587  We use odd numbers to indicate the existence of significant changes;
   588  and while usually we try to tag an even-number release between each odd number release so that migrations can be smoothed out,
   589  in this case there simply weren't enough interesting points in between to be worth doing so.
   590  
   591  - Change: linking has been significantly reworked, and now primarily works through the `ipld.LinkSystem` type.
   592  	- This is cool, because it makes a lot of things less circuitous.  Previously, working with links was a complicated combination of Loader and Storer functions, the Link interface contained the Load method, it was just... complicated to figure out where to start.  Now, the answer is simple and constant: "Start with LinkSystem".  Clearer to use; clearer to document; and also coincidentally a lot clearer to develop for, internally.
   593  	- The PR can be found here: https://github.com/ipld/go-ipld-prime/pull/143
   594  	- `Link.Load` -> `LinkSystem.Load` (or, new: `LinkSystem.Fill`, which lets you control memory allocation more explicitly).
   595  	- `LinkBuilder.Build` -> `LinkSystem.Store`.
   596  	- `LinkSystem.ComputeLink` is a new feature that produces a Link without needing to store the data anywhere.
   597  	- The `ipld.Loader` function is now most analogous to `ipld.BlockReadOpener`.  You now put it into use by assigning it to a `LinkLoader`'s `StorageReadOpener` field.
   598  	- The `ipld.Storer` function is now most analogous to `ipld.BlockWriteOpener`.  You now put it into use by assigning it to a `LinkLoader`'s `StorageWriteOpener` field.
   599  	- 99% of the time, you'll probably start with `linking/cid.DefaultLinkSystem()`.  You can assign to fields of this to customize it further, but it'll get you started with multihashes and multicodecs and all the behavior you expect when working with CIDs.
   600  		- (So, no -- the `cidlink` package hasn't gone anywhere.  Hopefully it's a bit less obtrusive now, but it's still here.)
   601  	- The `traversal` package's `Config` struct now uses a `LinkSystem` instead of a `Loader` and `Storer` pair, as you would now probably expect.
   602  		- If you had code that was also previously passing around `Loader` and `Storer`, it's likely a similar pattern of change will be the right direction for that code.
   603  	- In the _future_, further improvements will come from this: we're now much, much closer to making a bunch of transitive dependencies become optional (especially, various hashers, which currently, whenever you pull in the `linking/cid` package, come due to `go-cid`, and are quite large).  When these improvements land (again, they're not in this release), you'll need to update your applications to import hashers you need if they're not in the golang standard library.  For now: there's no change.
   604  - Change: multicodec registration is now in the `go-ipld-prime/multicodec` package.
   605  	- Previously, this registry was in the `linking/cid` package.  These things are now better decoupled.
   606  	- This will require packages which register codecs to make some very small updates: e.g. `s/cidlink.RegisterMulticodecDecoder/multicodec.RegisterDecoder/`, and correspondingly, update the package imports at the top of the file.
   607  - New: some pre-made storage options (e.g. satisfying the `ipld.StorageReadOpener` and `ipld.StorageWriteOpener` function interfaces) have appeared!  Find these in the `go-ipld-prime/storage` package.
   608  	- Currently this only includes a simple in-memory storage option.  This may be useful for testing and examples, but probably not much else :)
   609  	- These are mostly intended to be illustrative.  You should still expect to find better storage mechanisms in other repos.
   610  - Change: some function names in codec packages are ever-so-slightly updated.  (They're verbs now, instead of nouns, which makes sense because they're functions.  I have no idea what I was thinking with the previous naming.  Sorry.)
   611  	- `s/dagjson.Decoder/dagjson.Decode/g`
   612  	- `s/dagjson.Decoder/dagjson.Encode/g`
   613  	- `s/dagcbor.Decoder/dagcbor.Decode/g`
   614  	- `s/dagcbor.Encoder/dagcbor.Encode/g`
   615  	- If you've only been using these indirectly, via their multicodec indicators, you won't have to update anything at all to account for this change.
   616  - New: several new forms of helpers to make it syntactically easy to create new IPLD data trees with golang code!
   617  	- Check out the `go-ipld-prime/fluent/quip` package!  See https://github.com/ipld/go-ipld-prime/pull/134, where it was introduced, for more details.
   618  	- Check out the `go-ipld-prime/fluent/qp` package!  See https://github.com/ipld/go-ipld-prime/pull/138, where it was introduced, for more details.
   619  	- Both of these offer variations on `fluent` which have much lower costs to use.  (`fluent` incurs allocations during operation, which has a noticable impact on performance if used in a "hot" code path.  Neither of these two new solutions do!)
   620  	- For now, both `quip` and `qp` will be maintained.  They have similar goals, but different syntaxes.  If one is shown drastically more popular over time, we might begin to consider deprecating one in favor of the other, but we'll need lots of data before considering that.
   621  	- We won't be removing the `fluent` package anytime soon, but we probably wouldn't recommend building new stuff on it.  `qp` and `quip` are both drastically preferable for performance reasons.
   622  - New: there is now an interface called `ipld.ADL` which can be used for a certain kind of feature detection.
   623  	- This is an experimental new concept and likely subject to change.
   624  	- The one key trait we've found all ADLs tend to share right now is that they have a "synthesized" view and "substrate" view of their data.  So: the `ipld.ADL` interface states that a thing is an `ipld.Node` (for the synthesized view), and from it you should be able to access a `Substrate() ipld.Node`, and that's about it.
   625  
   626  
   627  
   628  ### v0.7.0
   629  
   630  _2020 December 31_
   631  
   632  v0.7.0 is a small release that makes a couple of breaking changes since v0.6.0.
   633  However, the good news is: they're all very small changes, and we've kept them in a tiny group,
   634  so if you're already on v0.6.0, this update should be easy.
   635  And we've got scripts to help you.
   636  
   637  There's also one cool new feature: `traversal.FocusedTransform` is now available to help you make mutations to large documents conveniently.
   638  
   639  - Change: all interfaces and APIs now use golang `int64` rather than golang `int`.  [#125](https://github.com/ipld/go-ipld-prime/pull/125)
   640  	- This is necessary because the IPLD Data Model specifies that integers must be "at least 2^53" in range, and so since go-ipld-prime may also be used on 32-bit architectures, it is necessary that we not use the `int` type, which would fail to be Data Model-compliant on those architectures.
   641  	- The following GNU sed lines should assist this transition in your code, although some other changes that are more difficult automate may also be necessary:
   642  		```
   643  		sed -ri 's/(func.* AsInt.*)\<int\>/\1int64/g' **/*.go
   644  		sed -ri 's/(func.* AssignInt.*)\<int\>/\1int64/g' **/*.go
   645  		sed -ri 's/(func.* Length.*)\<int\>/\1int64/g' **/*.go
   646  		sed -ri 's/(func.* LookupByIndex.*)\<int\>/\1int64/g' **/*.go
   647  		sed -ri 's/(func.* Next.*)\<int\>/\1int64/g' **/*.go
   648  		sed -ri 's/(func.* ValuePrototype.*)\<int\>/\1int64/g' **/*.go
   649  		```
   650  - Change: we've renamed the types talking about "kinds" for greater clarity.  `ipld.ReprKind` is now just `ipld.Kind`; `schema.Kind` is now `schema.TypeKind`.  We expect to use "kind" and "typekind" consistently in prose and documentation from now on, as well.  [#127](https://github.com/ipld/go-ipld-prime/pull/127)
   651  	- Pretty much everyone who's used this library has said "ReprKind" didn't really make sense as a type name, so, uh, yeah.  You were all correct.  It's fixed now.
   652  	- "kind" now always means "IPLD Data Model kind", and "typekind" now always means "the kinds which an IPLD Schema type can have".
   653  	- You can find more examples of how we expect to use this in a sentence from now on in the discussion that lead to the rename: https://github.com/ipld/go-ipld-prime/issues/94#issuecomment-745307919
   654  	- The following GNU sed lines should assist this transition in your code:
   655  		```
   656  		sed -ri 's/\<Kind\(\)/TypeKind()/g' **/*.go
   657  		sed -ri 's/\<Kind_/TypeKind_/g' **/*.go
   658  		sed -i 's/\<Kind\>/TypeKind/g' **/*.go
   659  		sed -i 's/ReprKind/Kind/g' **/*.go
   660  		```
   661  - Feature: `traversal.FocusedTransform` works now!  :tada:  You can use this to take a node, say what path inside it you want to update, and then give it an updated value.  Super handy.  [#130](https://github.com/ipld/go-ipld-prime/pull/130)
   662  
   663  
   664  ### v0.6.0
   665  
   666  _2020 December 14_
   667  
   668  v0.6.0 is a feature-packed release and has a few bugfixes, and _no_ significant breaking changes.  Update at your earliest convenience.
   669  
   670  Most of the features have to do with codegen, which we now consider to be in **alpha** -- go ahead and use it!  (We're starting to self-host some things in it, so any changes will definitely be managed from here on out.)
   671  A few other small handy helper APIs have appeared as well; see the detailed notes for those.
   672  
   673  Like with the last couple of releases, our intent is to follow this smooth-sailing change with another release shortly which will include some minor but noticable API changes, and that release may require you to make some code changes.
   674  Therefore, we suggest upgrading to this one first, beacuse it's an easy waypoint before the next change.
   675  
   676  - Feature: codegen is a reasonably usable alpha!  We now encourage trying it out (but still only for those willing to experience an "alpha" level of friction -- UX still rough, and we know it).
   677  	- Consult the feature table in the codegen package readme: many major features of IPLD Schemas are now supported.
   678  		- Structs with tuple representations?  Yes.
   679  		- Keyed unions?  Yes.
   680  		- Structs with stringjoin representations?  Yes.  Including nested?  _Yes_.
   681  		- Lots of powerful stuff is now available to use.
   682  		- See [the feature table in the codegen readme](https://github.com/ipld/go-ipld-prime/blob/v0.6.0/schema/gen/go/README.md#completeness) for details.
   683  	- Many generated types now have more methods for accessing them in typed ways (in addition to the usual `ipld.Node` interfaces, which can access the same data, but lose explicit typing).  [#106](https://github.com/ipld/go-ipld-prime/pull/106)
   684  		- Maps and lists now have both lookup methods and iterators which know the type of the child keys and values explicitly.
   685  	- Cool: when generating unions, you can choose between different implementation strategies (favoring either interfaces, or embedded values) by using Adjunct Config.  This lets you tune for either speed (reduced allocation count) or memory footprint (less allocation size, but more granular allocations).
   686  		- See notes in [#60](https://github.com/ipld/go-ipld-prime/pull/60) for more detail on this.  We'll be aiming to make configurability of this more approachable and better documented in future releases, as we move towards codegen tools usable as CLI tools.
   687  	- Cyclic references in types are now supported.
   688  		- ... mostly.  Some manual configuration may sometimes be required to make sure the generated structure wouldn't have an infinite memory size.  We'll keep working on making this smoother in the future.
   689  	- Field symbol overrides now work properly.  (E.g., if you have a schema with a field called "type", you can make that work now.  Just needs a field symbol override in the Adjunct Config when doing codegen!)
   690  	- Codegen'd link types now implemented the `schema.TypedLinkNode` interface where applicable.
   691  	- Structs now actually validate all required fields are present before allowing themselves to finish building.  Ditto for their map representations.
   692  	- Much more testing.  And we've got a nice new declarative testcase system that makes it easier to write descriptions of how data should behave (at both the typed and representation view levels), and then just call one function to run exhaustive tests to make sure it looks the same from every inspectable API.
   693  	- Change: codegen now outputs a fixed set of files.  (Previously, it output one file per type in your schema.)  This makes codegen much more managable; if you remove a type from your schema, you don't have to chase down the orphaned file.  It's also just plain less clutter to look at on the filesystem.
   694  - Demo: as proof of the kind of work that can be done now with codegen, we've implemented the IPLD Schema schema -- the schema that describes IPLD Schema declarations -- using codegen.  It's pretty neat.
   695  	- Future: we'll be replacing most of the current current `schema` package with code based on this generated stuff.  Not there yet, though.  Taking this slow.
   696  		- You can see the drafts of this, along with new features based on it, in [#107](https://github.com/ipld/go-ipld-prime/pull/107).
   697  - Feature: the `schema` typesystem info packages are improved.
   698  	- Cyclic references in types are now supported.
   699  		- (Mind that there are still some caveats about this when fed to codegen, though.)
   700  	- Graph completeness is now validated (e.g. missing type references emit useful errors)!
   701  - Feature: there's a `traversal.Get` function.  It's like `traversal.Focus`, but just returns the reached data instead of dragging you through a callback.  Handy.
   702  - Feature/bugfix: the DAG-CBOR codec now includes resource budgeting limits.  This means it's a lot harder for a badly-formed (or maliciously formed!) message to cause you to run out of memory while processing it.  [#85](https://github.com/ipld/go-ipld-prime/pull/85)
   703  - Bugfix: several other panics from the DAG-CBOR codec on malformed data are now nice politely-returned errors, as they should be.
   704  - Bugfix: in codegen, there was a parity break between the AssembleEntry method and AssembleKey+AssembleValue in generated struct NodeAssemblers.  This has been fixed.
   705  - Minor: ErrNoSuchField now uses PathSegment instead of a string.  You probably won't notice (but this was important interally: we need it so we're able to describe structs with tuple representations).
   706  - Bugfix: an error path during CID creation is no longer incorrectly dropped.  (I don't think anyone ever ran into this; it only handled situations where the CID parameters were in some way invalid.  But anyway, it's fixed now.)
   707  - Performance: when `cidlink.Link.Load` is used, it will do feature detection on its `io.Reader`, and if it looks like an already-in-memory buffer, take shortcuts that do bulk operations.  I've heard this can reduce memory pressure and allocation counts nicely in applications where that's a common scenario.
   708  - Feature: there's now a `fluent.Reflect` convenience method.  Its job is to take some common golang structs like maps and slices of primitives, and flip them into an IPLD Node tree.  [#81](https://github.com/ipld/go-ipld-prime/pull/81)
   709  	- This isn't very high-performance, so we don't really recommend using it in production code (certainly not in any hot paths where performance matters)... but it's dang convenient sometimes.
   710  - Feature: there's now a `traversal.SelectLinks` convenience method.  Its job is to walk a node tree and return a list of all the link nodes.  [#110](https://github.com/ipld/go-ipld-prime/pull/110)
   711  	- This is both convenient, and faster than doing the same thing using general-purpose Selectors (we implemented it as a special case).
   712  - Demo: you can now find a "rot13" ADL in the `adl/rot13adl` package.  This might be useful reference material if you're interested in writing an ADL and wondering what that entails.  [#98](https://github.com/ipld/go-ipld-prime/pull/98)
   713  - In progress: we've started working on some new library features for working with data as streams of "tokens".  You can find some of this in the new `codec/codectools` package.
   714  	- Functions are available for taking a stream of tokens and feeding them into a NodeAssembler; and for taking a Node and reading it out as a stream of tokens.
   715  	- The main goal in mind for this is to provide reusable components to make it easier to implement new codecs.  But maybe there will be other uses for this feature too!
   716  	- These APIs are brand new and are _extremely subject to change_, much more so than any other packages in this repo.  If you work with them at this stage, _do_ expect to need to update your code when things shift.
   717  
   718  
   719  ### v0.5.0
   720  
   721  _2020 July 2_
   722  
   723  v0.5.0 is a small release -- it just contains a bunch of renames.
   724  There are _no_ semantic changes bundled with this (it's _just_ renames) so this should be easy to absorb.
   725  
   726  - Renamed: `NodeStyle` -> `NodePrototype`.
   727  	- Reason: it seems to fit better!  See https://github.com/ipld/go-ipld-prime/issues/54 for a full discussion.
   728  	- This should be a "sed refactor" -- the change is purely naming, not semantics, so it should be easy to update your code for.
   729  	- This also affects some package-scoped vars named `Style`; they're accordingly also renamed to `Prototype`.
   730  	- This also affects several methods such as `KeyStyle` and `ValueStyle`; they're accordingly also renamed to `KeyPrototype` and `ValuePrototype`.
   731  - Renamed: `(Node).Lookup{Foo}` -> `(Node).LookupBy{Foo}`.
   732  	- Reason: The former phrasing makes it sound like the "{Foo}" component of the name describes what it returns, but in fact what it describes is the type of the param (which is necessary, since Golang lacks function overloading parametric polymorphism).  Adding the preposition should make this less likely to mislead (even though it does make the method name moderately longer).
   733  	- This should be a "sed refactor" -- the change is purely naming, not semantics, so it should be easy to update your code for.
   734  - Renamed: `(Node).Lookup` -> `(Node).LookupNode`.
   735  	- Reason: The shortest and least-qualified name, 'Lookup', should be reserved for the best-typed variant of the method, which is only present on codegenerated types (and not present on the Node interface at all, due to Golang's limited polymorphism).
   736  	- This should be a "sed refactor" -- the change is purely naming, not semantics, so it should be easy to update your code for.  (The change itself in the library was fairly literally `s/Lookup(/LookupNode(/g`, and then `s/"Lookup"/"LookupNode"/g` to catch a few error message strings, so consumers shouldn't have it much harder.)
   737  	- Note: combined with the above rename, this method overall becomes `(Node).LookupByNode`.
   738  - Renamed: `ipld.Undef` -> `ipld.Absent`, and `(Node).IsUndefined` -> `(Node).IsAbsent`.
   739  	- Reason: "absent" has emerged as a much, much better description of what this value means.  "Undefined" sounds nebulous and carries less meaning.  In long-form prose docs written recently, "absent" consistently fits the sentence flow much better.  Let's just adopt "absent" consistently and do away with "undefined".
   740  	- This should be a "sed refactor" -- the change is purely naming, not semantics, so it should be easy to update your code for.
   741  
   742  
   743  ### v0.4.0
   744  
   745  v0.4.0 contains some misceleanous features and documentation improvements -- perhaps most notably, codegen is re-introduced and more featureful than previous rounds -- but otherwise isn't too shocking.
   746  This tag mostly exists as a nice stopping point before the next version coming up (which is planned to include several API changes).
   747  
   748  - Docs: several new example functions should now appear in the godoc for how to use the linking APIs.
   749  - Feature: codegen is back!  Use it if you dare.
   750  	- Generated code is now up to date with the present versions of the core interfaces (e.g., it's updated for the NodeAssembler world).
   751  	- We've got a nice big feature table in the codegen package readme now!  Consult that to see which features of IPLD Schemas now have codegen support.
   752  	- There are now several implemented and working (and robustly tested) examples of codegen for various representation strategies for the same types.  (For example, struct-with-stringjoin-representation.)  Neat!
   753  	- This edition of codegen uses some neat tricks to not just maintain immutability contracts, but even prevent the creation of zero-value objects which could potentially be used to evade validation phases on objects that have validation rules.  (This is a bit experimental; we'll see how it goes.)
   754  	- There are oodles and oodles of deep documentation of architecture design choices recorded in "HACKME_*" documents in the codegen package that you may enjoy if you want to contribute or understand why generated things are the way they are.
   755  	- Testing infrastructure for codegen is now solid.  Running tests for the codegen package will: exercise the generation itself; AND make sure the generated code compiles; AND run behavioral tests against it: the whole gamut, all from regular `go test`.
   756  	- The "node/gendemo" package contains a real example of codegen output... and it's connected to the same tests and benchmarks as other node implementations.  (Are the gen'd types fast?  yes.  yes they are.)
   757  	- There's still lots more to go: interacting with the codegen system still requires writing code to interact with as a library, as we aren't shipping a CLI frontend to it yet; and many other features are still in development as well.  But you're welcome to take it for a spin if you're eager!
   758  - Feature: introduce JSON Tables Codec ("JST"), in the `codec/jst` package.  This is a codec that emits bog-standard JSON, but leaning in on the non-semantic whitespace to produce aligned output, table-like, for pleasant human reading.  (If you've used `column -t` before in the shell: it's like that.)
   759  	- This package may be a temporary guest in this repo; it will probably migrate to its own repo soon.  (It's a nice exercise of our core interfaces, though, so it incubated here.)
   760  - I'm quietly shifting the versioning up to the 0.x range.  (Honestly, I thought it was already there, heh.)  That makes this this "v0.4".
   761  
   762  
   763  ### v0.0.3
   764  
   765  v0.0.3 contained a massive rewrite which pivoted us to using NodeAssembler patterns.
   766  Code predating this version will need significant updates to match; but, the performance improvements that result should be more than worth it.
   767  
   768  - Constructing new nodes has a major pivot towards using "NodeAssembler" pattern: https://github.com/ipld/go-ipld-prime/pull/49
   769  	- This was a massively breaking change: it pivoted from bottom-up composition to top-down assembly: allocating large chunks of structured memory up front and filling them in, rather than stitching together trees over fragmented heap memory with lots of pointers
   770  - "NodeStyle" and "NodeBuilder" and "NodeAssembler" are all now separate concepts:
   771  	- NodeStyle is more or less a builder factory (forgive me -- but it's important: you can handle these without causing allocations, and that matters).
   772  	  Use NodeStyle to tell library functions what kind of in-memory representation you want to use for your data.  (Typically `basicnode.Style.Any` will do -- but you have the control to choose others.)
   773  	- NodeBuilder allocates and begins the assembly of a value (or a whole tree of values, which may be allocated all at once).
   774  	- NodeAssembler is the recursive part of assembling a value (NodeBuilder implements NodeAssembler, but everywhere other than the root, you only use the NodeAssembler interface).
   775  - Assembly of trees of values now simply involves asking the assembler for a recursive node to give you assemblers for the keys and/or values, and then simply... using them.
   776  	- This is much simpler (and also faster) to use than the previous system, which involved an awkward dance to ask about what kind the child nodes were, get builders for them, use those builders, then put the result pack in the parent, and so forth.
   777  - Creating new maps and lists now accepts a size hint argument.
   778  	- This isn't strictly enforced (you can provide zero, or even a negative number to indicate "I don't know", and still add data to the assembler), but may improve efficiency by reducing reallocation costs to grow structures if the size can be estimated in advance.
   779  - Expect **sizable** performance improvements in this version, due to these interface changes.
   780  - Some packages were renamed in an effort to improve naming consistency and feel:
   781  	- The default node implementations have moved: expect to replace `impl/free` in your package imports with `node/basic` (which is an all around better name, anyway).
   782  	- The codecs packages have moved: replace `encoding` with `codec` in your package imports (that's all there is to it; nothing else changed).
   783  - Previous demos of code generation are currently broken / disabled / removed in this tag.
   784  	- ...but they'll return in future versions, and you can follow along in branches if you wish.
   785  - Bugfix: dag-cbor codec now correctly handles marshalling when bytes come after a link in the same object. [[53](https://github.com/ipld/go-ipld-prime/pull/53)]
   786  
   787  ### v0.0.2
   788  
   789  - Many various performance improvements, fixes, and docs improvements.
   790  - Many benchmarks and additional tests introduced.
   791  - Includes early demos of parts of the schema system, and early demos of code generation.
   792  - Mostly a checkpoint before beginning v0.0.3, which involved many large API reshapings.
   793  
   794  ### v0.0.1
   795  
   796  - Our very first tag!
   797  - The central `Node` and `NodeBuilder` interfaces are already established, as is `Link`, `Loader`, and so forth.
   798    You can already build generic data handling using IPLD Data Model concepts with these core interfaces.
   799  - Selectors and traversals are available.
   800  - Codecs for dag-cbor and dag-json are batteries-included in the repo.
   801  - There was quite a lot of work done before we even started tagging releases :)