Rename migration tool to boxo-migrate, tidy up, and add docs

README.md

@@ -20,6 +20,7 @@ Boxo 🍌
     - [Does Boxo == IPFS?](#does-boxo--ipfs)
     - [Is everything related to IPFS in the Go ecosystem in this repo?](#is-everything-related-to-ipfs-in-the-go-ecosystem-in-this-repo)
 - [Getting started](#getting-started)
+- [Migrating to Boxo](#migrating-to-boxo)
 - [Should I add my IPFS component to Boxo?](#should-i-add-my-ipfs-component-to-boxo)
 - [Help](#help)
 - [Governance and Access](#governance-and-access)
@@ -69,7 +70,7 @@ No.  This repo houses some IPFS functionality written in Go that has been useful
 
 ### Is everything related to IPFS in the Go ecosystem in this repo?
 
-No.  Not everything related to IPFS is intended to be in Boxo. View it as a starter toolbox (potentially among multiple).  If you’d like to build an IPFS implementation with Go, here are some tools you might want that are maintained by a group that has long term commitments to the IPFS project.  There are certainly repos that others maintainer that aren't included here (e.g., ipfs/go-car) which are still useful to IPFS implementations. It's expected and fine for new IPFS functionality to be developed that won't be part of Boxo.  
+No.  Not everything related to IPFS is intended to be in Boxo. View it as a starter toolbox (potentially among multiple).  If you’d like to build an IPFS implementation with Go, here are some tools you might want that are maintained by a group that has long term commitments to the IPFS project.  There are certainly repos that others maintainer that aren't included here (e.g., ipfs/go-car) which are still useful to IPFS implementations. It's expected and fine for new IPFS functionality to be developed that won't be part of Boxo.
 
 ### Why is the code coverage so bad?
 
@@ -78,6 +79,24 @@ The code coverage of this repo is not currently representative of the actual tes
 ## Getting started
 See [examples](./examples/README.md).
 
+If you are migrating to Boxo, see [Migrating to Boxo](#migrating-to-boxo).
+
+## Migrating to Boxo
+Many Go modules under github.com/ipfs have moved here. Boxo provides a tool to ease this migration, which does most of the work for you:
+
+* `cd` into the root directory of your module (where the `go.mod` file is)
+* Run: `go run github.com/ipfs/boxo/cmd/boxo-migrate@latest update-imports`
+  * This will upgrade your module to Boxo v0.8.0 and rewrite your import paths
+* Run: `go run github.com/ipfs/boxo/cmd/boxo-migrate@latest check-dependencies`
+  * This will print unmaintained dependencies you still have
+  * These aren't necessarily an immediate problem, but you should eventually get them out of your dependency graph
+
+This tool only upgrades your module to Boxo v0.8.0, to minimize backwards-incompatible changes. Depending on the versions of IPFS modules before the upgrade, your code may require additional changes to build.
+
+We recommend upgrading to v0.8.0 first, and _then_ upgrading to the latest Boxo release.
+
+If you encounter any challenges, please [open an issue](https://github.com/ipfs/boxo/issues/new/choose) and Boxo maintainers will help you.
+
 ## Should I add my IPFS component to Boxo?
 We happily accept external contributions! However, Boxo maintains a high quality bar, so code accepted into Boxo must meet some minimum maintenance criteria:
 

cmd/migrate/migrate.go → cmd/boxo-migrate/boxomigrate.go

@@ -6,7 +6,7 @@ import (
 	"os"
 	"strings"
 
-	migrate "github.com/ipfs/boxo/cmd/migrate/internal"
+	migrate "github.com/ipfs/boxo/cmd/boxo-migrate/internal"
 	"github.com/urfave/cli/v2"
 )
 
@@ -64,10 +64,31 @@ func main() {
 					if err != nil {
 						return err
 					}
+
+					fmt.Printf("\n\n")
+
+					if !dryrun {
+						err := migrator.GoGet("github.com/ipfs/boxo@v0.8.0-rc3")
+						if err != nil {
+							return err
+						}
+					}
+
 					if err := migrator.UpdateImports(); err != nil {
 						return err
 					}
 
+					if dryrun {
+						return nil
+					}
+
+					if err := migrator.GoModTidy(); err != nil {
+						return err
+					}
+
+					fmt.Printf("Your code has been successfully updated. Note that you might still need to manually fix up parts of your code.\n\n")
+					fmt.Printf("You should also consider running the 'boxo-migrate check-dependencies' command to see if you have any other dependencies on migrated code.\n\n")
+
 					return nil
 				},
 			},
@@ -88,7 +109,7 @@ func main() {
 					}
 					if len(deps) > 0 {
 						fmt.Println(strings.Join([]string{
-							"You still have dependencies on repos which have migrated to go-libipfs.",
+							"You still have dependencies on repos which have migrated to Boxo.",
 							"You should consider not having these dependencies to avoid multiple versions of the same code.",
 							"You can use 'go mod why' or 'go mod graph' to find the reason for these dependencies.",
 							"",

cmd/migrate/go.mod → cmd/boxo-migrate/go.mod

@@ -1,4 +1,4 @@
-module github.com/ipfs/boxo/cmd/migrate
+module github.com/ipfs/boxo/cmd/boxo-migrate
 
 go 1.19
 

cmd/migrate/internal/migrator.go → cmd/boxo-migrate/internal/migrator.go

@@ -106,6 +106,17 @@ func (m *Migrator) run(cmdName string, args ...string) (int, string, string, err
 	return state.ExitCode(), strings.TrimSpace(stdout.String()), strings.TrimSpace(stderr.String()), nil
 }
 
+func (m *Migrator) runOrErr(cmdName string, args ...string) (string, error) {
+	exitCode, stdout, stderr, err := m.run(cmdName, args...)
+	if err != nil {
+		return "", err
+	}
+	if exitCode != 0 {
+		return "", fmt.Errorf("non-zero exit code %d, stderr:\n%s", exitCode, stderr)
+	}
+	return stdout, nil
+}
+
 // FindMigratedDependencies returns a list of dependent module versions like 'module v0.1.0' that have been migrated to go-libipfs.
 func (m *Migrator) FindMigratedDependencies() ([]string, error) {
 	var modVersions []string
@@ -129,13 +140,10 @@ func (m *Migrator) FindMigratedDependencies() ([]string, error) {
 }
 
 func (m *Migrator) findSourceFiles() ([]string, error) {
-	exitCode, stdout, stderr, err := m.run("go", "list", "-json", "./...")
+	stdout, err := m.runOrErr("go", "list", "-json", "./...")
 	if err != nil {
 		return nil, fmt.Errorf("finding source files: %w", err)
 	}
-	if exitCode != 0 {
-		return nil, fmt.Errorf("non-zero exit code %d finding source files, stderr:\n%s", exitCode, stderr)
-	}
 
 	var files []string
 	dec := json.NewDecoder(strings.NewReader(stdout))
@@ -166,3 +174,21 @@ func (m *Migrator) UpdateImports() error {
 	}
 	return nil
 }
+
+func (m *Migrator) GoModTidy() error {
+	fmt.Printf("\n\nRunning 'go mod tidy'...\n\n")
+	_, err := m.runOrErr("go", "mod", "tidy")
+	if err != nil {
+		return fmt.Errorf("running 'go mod tidy': %w", err)
+	}
+	return nil
+}
+
+func (m *Migrator) GoGet(mod string) error {
+	fmt.Printf("Adding module: %q\n\n", mod)
+	_, err := m.runOrErr("go", "get", mod)
+	if err != nil {
+		return fmt.Errorf("running 'go get %s': %w", mod, err)
+	}
+	return nil
+}