Migrating library APIs

[wking]

As discussed in #1158, sometimes we want to make changes to our public library APIs. How should we do that? Do we need ‘gofix’ style translators? Should we be logging runtime deprecation warnings? Some folks do some sed-like things with go fmt. Maybe we're just explaining migrations in our release notes? What do we want this to look like?

I'm currently leaning towards a well-definied distinction between stable (core/…) and fluxy (shell/…`) APIs (see #1158), with migration suggestions in the release notes whenever we make a backwards-incompatible change to an existing API. Since I can't find a way to get compile-time deprecation warnings in Go, I'd suggest this strategy:

1. Implement new interface using a new function name (to not collide with the existing usage).

2. Add a mention of the new interface (and deprecated old interface) to all subsequent release notes, giving a target version for the actual removal. For example:

   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, which we won't land before 2015-09-01. 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()
   

3. Keep printing that deprecation warning and migration advice in subsequent release notes leading up to 0.4.0.

4. Cut 0.4.0 with a prominent list of removals and migration advice.

Once we get to 1.0, things like this will hopefully happen less frequently (if we do a good job planning the API now), so the gaps between backwards-incompatible changes should be larger.

Spun off from ipfs/team-mgmt#6.

[Stebalien]

Superseded by the "CoreAPI" interfaces.