github.com/ipld/go-ipld-prime@v0.21.0/linking/cid/HACKME.md (about)

     1  Why does this package exist?
     2  ----------------------------
     3  
     4  The `linking/cid` package bends the `github.com/ipfs/go-cid` package into conforming to the `ipld.Link` interface.
     5  
     6  The `linking/cid` package also contains factory functions for `ipld.LinkSystem`.
     7  These LinkSystem will be constructed with `EncoderChooser`, `DecoderChooser`, and `HasherChooser` funcs
     8  which will use multicodec registries and multihash registries respectively.
     9  
    10  ### Why not use go-cid directly?
    11  
    12  We need a "Link" interface in the root `ipld` package or things just aren't definable.
    13  But we don't want the root `ipld.Link` concept to directly map to `go-cid.Cid` for several reasons:
    14  
    15  1. We might want to revisit the go-cid library.  Possibly in the "significantly breaking changes" sense.
    16  	- It's also not clear when we might do this -- and if we do, the transition period will be *long* because it's a highly-depended-upon library.
    17  	- See below for some links to a gist that discusses why.
    18  2. We might want to extend the concept of linking to more than just plain CIDs.
    19  	- This is hypothetical at present -- but an often-discussed example is "what if CID+Path was also a Link?"
    20  3. We might sometimes want to use IPLD libraries without using any CID implementation at all.
    21  	- e.g. it's totally believable to want to use IPLD libraries for handling JSON and CBOR, even if you don't want IPLD linking.
    22  	- if the CID packages were cheap enough, maybe this concern would fade -- but right now, they're **definitely** not; the transitive dependency tree of go-cid is *huge*.
    23  
    24  #### If go-cid is revisited, what might that look like?
    25  
    26  No idea.  (At least, not in a committal way.)
    27  
    28  https://gist.github.com/warpfork/e871b7fee83cb814fb1f043089983bb3#existing-implementations
    29  gathers some reflections on the problems that would be nice to solve, though.
    30  
    31  https://gist.github.com/warpfork/e871b7fee83cb814fb1f043089983bb3#file-cid-go
    32  contains a draft outline of what a revisited API could look like,
    33  but note that at the time of writing, it is not strongly ratified nor in any way committed to.
    34  
    35  At any rate, though, the operative question for this package is:
    36  if we do revisit go-cid, how are we going to make the transition managable?
    37  
    38  It seems unlikely we'd be able to make the transition manageable without some interface, somewhere.
    39  So we might as well draw that line at `ipld.Link`.
    40  
    41  (I hypothesize that a transition story might involve two CID packages,
    42  which could grow towards a shared interface,
    43  doing so in a way that's purely additive in the established `go-cid` package.
    44  We'd need two separate go modules to do this, since the aim is reducing dependency bloat for those that use the new one.
    45  The shared interface in this story could have more info than `ipld.Link` does now,
    46  but would nonetheless still certainly be an interface in order to support the separation of modules.)
    47  
    48  ### Why are LinkSystem factory functions here, instead of in the main IPLD package?
    49  
    50  Same reason as why we don't use go-cid directly.
    51  
    52  If we put these LinkSystem defaults in the root `ipld` package,
    53  we'd bring on all the transitive dependencies of `go-cid` onto an user of `ipld` unconditionally...
    54  and we don't want to do that.
    55  
    56  You know that Weird Al song "It's all about the pentiums"?
    57  Retune that in your mind to "It's all about dependencies".