v0.14.0

2021 November 11

This release is a smooth-sailing release, and mostly contains new features, quality-of-life improvements,
and some significant improvements to the completeness and usability of features that have been in development across previous releases.
There shouldn't be a lot of surprises, and upgrading should be easy.

Some of the biggest improvements include: bindnode now supports most IPLD features and is increasingly stable;
the schema system now has functioning schema/dmt and schema/dsl packages, and can parse schema documents smoothly(!);
if you haven't seen the printer package that first quietly appeared in v0.12.2, you should definitely check it out now;
and we have some new storage APIs that might be worth checking out, too.
There are also many, many other smaller improvements.

See the complete list and further deatils below
(and don't forget to check out the notes under the other v0.12.* headings, if you haven't absorbed those updates already, too!):

• New: datamodel.Copy: a helper function to do a shallow copy from one node to another.
  • You don't often need this, because nodes are supposed to be immutable!
    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.
• Improved: documentation of APIs. (Especially, for subtler bits like NodeAssembler.AssignNode.)
• 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.)
• New: a new storage API, including one batteries-included filesystem storage implementation, and adapters to several other different storage APIs. [#265, #279]
  • 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.
  • If you want to develop new storage systems or make adapters to them: the APIs in storage package are designed to be implemented easily.
    • 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!
    • 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.
  • 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.
    • 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.
  • 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.
  • As someone who already has code and wonders how to migrate:
    • If you're using the linking.Storage*Opener API: you don't have to do anything. Those still work too.
    • 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.)
  • 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.)
• 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.
  • 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.)
• New: a CLI tool has begun development!
  • ... and almost immediately been removed again, to live in its own repo: check out https://github.com/ipld/go-ipldtool .
• Improved: many more things about bindnode.
  • bindnode now understands go-cid.CID fields.
  • Kinded unions are much more completely supported.
  • Many TODO panics have gone away, replaced by finished features.
  • 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.
• Improved: the schema/dmt and schema/dsl packages are increasingly complete.
  • 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!
• 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!
  • 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.)
• 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.
• Improved: printer now supports links and bytes!
• 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.)

This, and the last few releases tagged in the v0.12.* series, include invaluable contributions from
@mvdan, @warpfork, @rvagg, @willscott, @masih, @hannahhoward, @aschmahmann, @ribasushi,
and probably yet more others who have contributed through code and design reviews,
or by using these libraries and demanding they continue to become better.
Thanks to each and every one of the people who carry this project forward!

---

In addition, the following minor releases have transpired since v0.12.0:

v0.12.3

2021 September 30

• Fixed: using SkipMe in a traversal now skips only that subtree of nodes, not the remainder of the block!
  [#251]
• 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.
  [#260]
• New: traversal features can be configured to visit links they encounter only once (and ignore them if seen again).
  [#252]
  • 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.
    This is because links are ignored when seen again, even if they're seen for a different reason, via a different path, etc.
• Fixed: a very nasty off-by-one in unions produced by the "gogen" codegen.
  [#257]
• 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).
• New: schema/dsl! This package contains parsers for the IPLD Schema DSL, and produces data structures in schema/dmt form.
• Removed: other misc partially-complete packages. (This will surely bother no one; it's just cleanup.)
• Removed: codec/jst. If you were using that, jst has its own repo now.
• Improved: traversal now uses the error wrapping ("%w") feature in more places.
• Changed: printer keeps empty maps and lists and strings on a single line.
• Changed: schema.TypeName is now just an alias of string. This may result in somewhat less casting; or, you might not notice it.
• Improved: the schema/dmt package continues to be improved and become more complete.
  • Some changes also track fixes in the schema spec, upstream. (Or caused those fixes!)
• New/Improved: the schema package describes several more things which it always should have. Enums, for example.

v0.12.2

2021 September 8

• 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]
  • This works for both plain data model data, and for typed data, and annotates type information if present.
  • 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.
• Fixed/Improved: more things about the bindnode system. (It's still early and improving fast.)
• 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.)
• 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.)

v0.12.1

2021 August 30

• Fixed/Improved: many things about the bindnode system. (It's still early and improving fast.)
• 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.)
• New: the root package contains more helper methods for encoding and decoding operations