From 6fce64e956e850a3af7ea16e85959c23e3eddc4b Mon Sep 17 00:00:00 2001 From: "Lixia (Sylvia) Lei" Date: Tue, 30 Apr 2024 10:22:57 +0800 Subject: [PATCH] docs: update migration guide and copy doc (#752) 1. Update MIGRATION_GUIDE.md 2. Revise the go doc comments for Copy and Extended Copy to make it easier to understand Resolve: #735 Signed-off-by: Lixia (Sylvia) Lei --- MIGRATION_GUIDE.md | 36 ++++++++++++++++++++++++++---------- copy.go | 12 ++++++++---- extendedcopy.go | 8 ++++++++ 3 files changed, 42 insertions(+), 14 deletions(-) diff --git a/MIGRATION_GUIDE.md b/MIGRATION_GUIDE.md index b9292f143..9a922f5a3 100644 --- a/MIGRATION_GUIDE.md +++ b/MIGRATION_GUIDE.md @@ -7,19 +7,21 @@ In version `v2`, ORAS Go library has been completely refreshed with: - Higher test coverage - Better documentation -**Besides, ORAS Go `v2` is now a registry client.** +**Additionally, ORAS Go `v2` is now a registry client.** ## Major Changes in `v2` -- Moves `content.FileStore` to [file.Store](https://pkg.go.dev/oras.land/oras-go/v2/content/file#Store) -- Moves `content.OCIStore` to [oci.Store](https://pkg.go.dev/oras.land/oras-go/v2/content/oci#Store) -- Moves `content.MemoryStore` to [memory.Store](https://pkg.go.dev/oras.land/oras-go/v2/content/memory#Store) -- Provides [SDK](https://pkg.go.dev/oras.land/oras-go/v2/registry/remote) to interact with OCI-compliant and Docker-compliant registries -- Supports [Copy](https://pkg.go.dev/oras.land/oras-go/v2#Copy) with more flexible options -- Supports [Extended Copy](https://pkg.go.dev/oras.land/oras-go/v2#ExtendedCopy) with options *(experimental)* -- No longer supports `docker.Login` and `docker.Logout` (removes the dependency on `docker`); instead, provides authentication through [auth.Client](https://pkg.go.dev/oras.land/oras-go/v2/registry/remote/auth#Client) - -Documentation and examples are available at [pkg.go.dev](https://pkg.go.dev/oras.land/oras-go/v2). +- Content store + - [`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) + - [`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) + - [`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) +- Registry interaction + - Introduces an [SDK](https://pkg.go.dev/oras.land/oras-go/v2/registry/remote) to interact with OCI-compliant and Docker-compliant registries +- Authentication + - 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) +- Copy operations + - 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 + - Enables [extended-copying](https://pkg.go.dev/oras.land/oras-go/v2#ExtendedCopy) of artifacts along with their predecessors (e.g., referrers) ## Migrating from `v1` to `v2` @@ -43,3 +45,17 @@ Documentation and examples are available at [pkg.go.dev](https://pkg.go.dev/oras Since breaking changes are introduced in `v2`, code refactoring is required for migrating from `v1` to `v2`. The migration can be done in an iterative fashion, as `v1` and `v2` can be imported and used at the same time. + +For comprehensive documentation and examples, please refer to [pkg.go.dev](https://pkg.go.dev/oras.land/oras-go/v2). + +## FAQs + +### Is there a 1:1 mapping of APIs between `v1` and `v2`? + +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. + +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. + +## Community Support + +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. diff --git a/copy.go b/copy.go index 2f131a8c6..adc30cb49 100644 --- a/copy.go +++ b/copy.go @@ -120,8 +120,11 @@ type CopyGraphOptions struct { FindSuccessors func(ctx context.Context, fetcher content.Fetcher, desc ocispec.Descriptor) ([]ocispec.Descriptor, error) } -// Copy copies a rooted directed acyclic graph (DAG) with the tagged root node -// in the source Target to the destination Target. +// Copy copies a rooted directed acyclic graph (DAG), such as an artifact, +// from the source Target to the destination Target. +// +// The root node (e.g. a tagged manifest of the artifact) is identified by the +// source reference. // The destination reference will be the same as the source reference if the // destination reference is left blank. // @@ -167,8 +170,9 @@ func Copy(ctx context.Context, src ReadOnlyTarget, srcRef string, dst Target, ds return root, nil } -// CopyGraph copies a rooted directed acyclic graph (DAG) from the source CAS to -// the destination CAS. +// CopyGraph copies a rooted directed acyclic graph (DAG), such as an artifact, +// from the source CAS to the destination CAS. +// The root node (e.g. a manifest of the artifact) is identified by a descriptor. func CopyGraph(ctx context.Context, src content.ReadOnlyStorage, dst content.Storage, root ocispec.Descriptor, opts CopyGraphOptions) error { return copyGraph(ctx, src, dst, root, nil, nil, nil, opts) } diff --git a/extendedcopy.go b/extendedcopy.go index 49b6264ec..e592394e9 100644 --- a/extendedcopy.go +++ b/extendedcopy.go @@ -65,6 +65,11 @@ type ExtendedCopyGraphOptions struct { // ExtendedCopy copies the directed acyclic graph (DAG) that are reachable from // the given tagged node from the source GraphTarget to the destination Target. +// In other words, it copies a tagged artifact along with its referrers or +// other predecessor manifests referencing it. +// +// The tagged node (e.g. a tagged manifest of the artifact) is identified by the +// source reference. // The destination reference will be the same as the source reference if the // destination reference is left blank. // @@ -98,6 +103,9 @@ func ExtendedCopy(ctx context.Context, src ReadOnlyGraphTarget, srcRef string, d // ExtendedCopyGraph copies the directed acyclic graph (DAG) that are reachable // from the given node from the source GraphStorage to the destination Storage. +// In other words, it copies an artifact along with its referrers or other +// predecessor manifests referencing it. +// The node (e.g. a manifest of the artifact) is identified by a descriptor. func ExtendedCopyGraph(ctx context.Context, src content.ReadOnlyGraphStorage, dst content.Storage, node ocispec.Descriptor, opts ExtendedCopyGraphOptions) error { roots, err := findRoots(ctx, src, node, opts) if err != nil {