core/coreunix/add: Deprecate Add

Folks should be using the node-returning AddFromReader defined in
shell/unixfs instead, since that creates the same node but returns the
dag.Node object itself, instead of the stringified key.  It's cheaper
to go from Node to stringified key than it is to go the other way
around, and you need the Node to do anything besides printing the
stringified key, so the shell/unixfs version has a better API and we
want to push people in that direction.  The shell/unixfs version also
uses our intended high-/low-level API distinction (core/... is for
low-level stuff) [1].  This commit starts the deprecation/migration
using the procedure outlined here [2], with the API-release-notes
directory proposed here [3] and accepted here [4].

[1]: #1158
[2]: #1159
[3]: https://github.com/ipfs/go-ipfs/pull/1136/files#r29379579
[4]: https://github.com/ipfs/go-ipfs/pull/1136/files#r29498385

core/coreunix/add.go

@@ -22,8 +22,12 @@ import (
 
 var log = eventlog.Logger("coreunix")
 
-// Add builds a merkledag from the a reader, pinning all objects to the local
-// datastore. Returns a key representing the root node.
+// DEPRECATED: Add builds a merkledag from the a reader, pinning all
+// objects to the local datastore. Returns a key representing the root
+// node.
+//
+// This function is deprecated and will be removed in 0.4.0.  You
+// should use shell/unixfs's AddFromReader instead.
 func Add(n *core.IpfsNode, r io.Reader) (string, error) {
 	// TODO more attractive function signature importer.BuildDagFromReader
 	dagNode, err := importer.BuildDagFromReader(

docs/release-notes/unreleased.md

@@ -0,0 +1,26 @@
+# `core/coreunix`'s `Add` → `shell/unixfs`'s `AddFromReader`
+
+We've added an `AddFromReader` function to `shell/unixfs`.  The old
+`Add` from `core/coreunix` is deprecated and will be removed in
+version 0.4.0. To update your existing code, change usage like:
+
+    keyString, err := coreunix.Add(ipfsNode, reader)
+    if err != nil {
+        return err
+    }
+
+to
+
+    fileNode, err := unixfs.AddFromReader(ipfsNode, reader)
+    if err != nil {
+        return err
+    }
+    key, err := fileNode.Key()
+    if err != nil {
+        return err
+    }
+    keyString := key.String()
+
+That's a bit more verbose if all you want is the stringified key, but
+returning a `dag.Node` makes it easier to perform other operations
+like adding the file node to a directory node.