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 <[email protected]>

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.

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)
 }

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 {