core/coreunix/add: Deprecate Add

Folks should be using the node-returning AddFromReader defined in
shell/fsnode 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/fsnode version has a better API and we
want to push people in that direction.  The shell/fsnode 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].

[1]: ipfs#1158
[2]: ipfs#1159

CHANGELOG.md

@@ -1,5 +1,36 @@
 # go-ipfs changelog
 
+### 0.3.4 - unreleased
+
+#### API changes
+
+##### `core/coreunix`'s `Add` → `shell/fsnode`'s `AddFromReader`
+
+We've added an `AddFromReader` function to `shell/fsutils`.  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 := fsutils.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.
+
 ### 0.3.3 - 2015-04-28
 
 This patch update fixes various issues, in particular:

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/fsnode's AddFromReader instead.
 func Add(n *core.IpfsNode, r io.Reader) (string, error) {
 	// TODO more attractive function signature importer.BuildDagFromReader
 	dagNode, err := importer.BuildDagFromReader(