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.