Skip to content

Commit cb788ab

Browse files
committed
feat: add migration documentation to README
1 parent 1eca368 commit cb788ab

File tree

2 files changed

+21
-1
lines changed

2 files changed

+21
-1
lines changed

.gitignore

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
cmd/boxo-migrate/boxo-migrate

README.md

Lines changed: 20 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,7 @@ Boxo 🍌
2020
- [Does Boxo == IPFS?](#does-boxo--ipfs)
2121
- [Is everything related to IPFS in the Go ecosystem in this repo?](#is-everything-related-to-ipfs-in-the-go-ecosystem-in-this-repo)
2222
- [Getting started](#getting-started)
23+
- [Migrating to Boxo](#migrating-to-boxo)
2324
- [Should I add my IPFS component to Boxo?](#should-i-add-my-ipfs-component-to-boxo)
2425
- [Help](#help)
2526
- [Governance and Access](#governance-and-access)
@@ -69,7 +70,7 @@ No. This repo houses some IPFS functionality written in Go that has been useful
6970

7071
### Is everything related to IPFS in the Go ecosystem in this repo?
7172

72-
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.
73+
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.
7374

7475
### Why is the code coverage so bad?
7576

@@ -78,6 +79,24 @@ The code coverage of this repo is not currently representative of the actual tes
7879
## Getting started
7980
See [examples](./examples/README.md).
8081

82+
If you are migrating to Boxo, see [Migrating to Boxo](#migrating-to-boxo).
83+
84+
## Migrating to Boxo
85+
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:
86+
87+
* `cd` into the root directory of your module (where the `go.mod` file is)
88+
* Run: `go run github.com/ipfs/boxo/cmd/boxo-migrate@latest update-imports`
89+
* This will upgrade your module to Boxo v0.8.0 and rewrite your import paths
90+
* Run: `go run github.com/ipfs/boxo/cmd/boxo-migrate@latest check-dependencies`
91+
* This will print unmaintained dependencies you still have
92+
* These aren't necessarily an immediate problem, but you should eventually get them out of your dependency graph
93+
94+
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.
95+
96+
We recommend upgrading to v0.8.0 first, and _then_ upgrading to the latest Boxo release.
97+
98+
If you encounter any challenges, please [open an issue](https://github.com/ipfs/boxo/issues/new/choose) and Boxo maintainers will help you.
99+
81100
## Should I add my IPFS component to Boxo?
82101
We happily accept external contributions! However, Boxo maintains a high quality bar, so code accepted into Boxo must meet some minimum maintenance criteria:
83102

0 commit comments

Comments
 (0)