oras.land/oras-go/v2@v2.5.1-0.20240520045656-aef90e4d04c4/MIGRATION_GUIDE.md (about) 1 # Migration Guide 2 3 In version `v2`, ORAS Go library has been completely refreshed with: 4 5 - More unified interfaces 6 - Notably fewer dependencies 7 - Higher test coverage 8 - Better documentation 9 10 **Additionally, ORAS Go `v2` is now a registry client.** 11 12 ## Major Changes in `v2` 13 14 - Content store 15 - [`content.File`](https://pkg.go.dev/oras.land/oras-go/pkg/content#File) is now [`file.Store`](https://pkg.go.dev/oras.land/oras-go/v2/content/file#Store) 16 - [`content.OCI`](https://pkg.go.dev/oras.land/oras-go/pkg/content#OCI) is now [`oci.Store`](https://pkg.go.dev/oras.land/oras-go/v2/content/oci#Store) 17 - [`content.Memory`](https://pkg.go.dev/oras.land/oras-go/pkg/content#Memory) is now [`memory.Store`](https://pkg.go.dev/oras.land/oras-go/v2/content/memory#Store) 18 - Registry interaction 19 - Introduces an [SDK](https://pkg.go.dev/oras.land/oras-go/v2/registry/remote) to interact with OCI-compliant and Docker-compliant registries 20 - Authentication 21 - Implements authentication through [`auth.Client`](https://pkg.go.dev/oras.land/oras-go/v2/registry/remote/auth#Client) and supports credential management via [`credentials`](https://pkg.go.dev/oras.land/oras-go/v2/registry/remote/credentials) 22 - Copy operations 23 - Enhances artifact [copying](https://pkg.go.dev/oras.land/oras-go/v2#Copy) capabilities between various [`Target`](https://pkg.go.dev/oras.land/oras-go/v2#Target) with flexible options 24 - Enables [extended-copying](https://pkg.go.dev/oras.land/oras-go/v2#ExtendedCopy) of artifacts along with their predecessors (e.g., referrers) 25 26 ## Migrating from `v1` to `v2` 27 28 1. Get the `v2` package 29 30 ```sh 31 go get oras.land/oras-go/v2 32 ``` 33 34 2. Import and use the `v2` package 35 36 ```go 37 import "oras.land/oras-go/v2" 38 ``` 39 40 3. Run 41 42 ```sh 43 go mod tidy 44 ``` 45 46 Since breaking changes are introduced in `v2`, code refactoring is required for migrating from `v1` to `v2`. 47 The migration can be done in an iterative fashion, as `v1` and `v2` can be imported and used at the same time. 48 49 For comprehensive documentation and examples, please refer to [pkg.go.dev](https://pkg.go.dev/oras.land/oras-go/v2). 50 51 ## FAQs 52 53 ### Is there a 1:1 mapping of APIs between `v1` and `v2`? 54 55 No, `v2` does not have a direct 1:1 mapping of APIs with `v1`, as the structure of the APIs has been significantly redesigned. Instead of looking for a direct replacement, see this as a chance to upgrade your application with `v2`'s new features. 56 57 You can explore the [end-to-end examples](https://pkg.go.dev/oras.land/oras-go/v2#pkg-overview) that demonstrate the usage of v2 in practical scenarios. 58 59 ## Community Support 60 61 If you encounter challenges during migration, seek assistance from the community by [submitting GitHub issues](https://github.com/oras-project/oras-go/issues/new) or asking in the [#oras](https://cloud-native.slack.com/archives/CJ1KHJM5Z) Slack channel.