update doc for pushing and artifacts

Signed-off-by: Shiwei Zhang <shizh@microsoft.com>

cmd/oras/push.go

@@ -90,7 +90,7 @@ Example - Push file to the HTTP registry:
 	cmd.Flags().StringVarP(&opts.password, "password", "p", "", "registry password")
 	cmd.Flags().BoolVarP(&opts.insecure, "insecure", "", false, "allow connections to SSL registry without certs")
 	cmd.Flags().BoolVarP(&opts.plainHTTP, "plain-http", "", false, "use plain http and not https")
-	cmd.Flags().BoolVarP(&opts.dryRun, "dry-run", "", false, "push to a dummy registry instead of the real remote")
+	cmd.Flags().BoolVarP(&opts.dryRun, "dry-run", "", false, "push to a dummy registry instead of the actual remote registry")
 	return cmd
 }
 
@@ -106,6 +106,7 @@ func runPush(opts pushOptions) error {
 	var resolver remotes.Resolver
 	if opts.dryRun {
 		resolver = iresolver.Dummy()
+		fmt.Println("Entered dry-run mode")
 	} else {
 		resolver = newResolver(opts.username, opts.password, opts.insecure, opts.plainHTTP, opts.configs...)
 	}

docs/README.md

@@ -7,3 +7,5 @@ In addition to the common usage, the advanced topics of `oras` are documented at
 - [Manifest Config](config.md)
 - [Manifest Annotations](annotations.md)
 - [Content Store](store.md)
+- [Advanced Push](push_adv.md)
+- [Artifact: Next Generation](artifact.md)

docs/artifact.md

@@ -0,0 +1,64 @@
+# Artifact: Next Generation
+
+`oras` is capable to push, discover, pull the artifact of [the next generation specification](https://github.com/notaryproject/artifacts/blob/prototype-2/specs-go/v2/artifact.go).
+
+## Push
+
+Pushing an artifact with the latest spec requires specifying the artifact type by the `--artifact-type` option.
+The `--artifact-reference` option accepts both tags and digests, where digests are suggested.
+
+For example, push a signature artifact `hello.jwt` of `application/vnd.cncf.notary.v2` type linking to another artifact `localhost:5000/test:latest`:
+
+```shell
+oras push localhost:5000/test \
+    --artifact-type application/vnd.cncf.notary.v2 \
+    --artifact-reference localhost:5000/test@sha256:c38fe4b80a6c5c23b211365408bdb8deeda5132cd802c988fb4cd0b972ccfb9f \
+    hello.jwt:application/vnd.cncf.notary.signature.v2+jwt
+```
+
+The output is
+
+```
+Uploading 556ec1d63c21 hello.jwt
+Pushed localhost:5000/test
+Digest: sha256:1b54b023fbbc174ea78aef6e3644c1f74f5b93e634d7e4bda486456bb3386791
+```
+
+## Pull
+
+Pulling an artifact is the same as the regular `oras pull`.
+
+For example, pull a signature artifact:
+
+```shell
+oras pull --media-type application/vnd.cncf.notary.signature.v2+jwt \
+    localhost:5000/test@sha256:1b54b023fbbc174ea78aef6e3644c1f74f5b93e634d7e4bda486456bb3386791
+```
+
+The output is
+
+```
+Downloaded 556ec1d63c21 hello.jwt
+Pulled localhost:5000/test@sha256:1b54b023fbbc174ea78aef6e3644c1f74f5b93e634d7e4bda486456bb3386791
+Digest: sha256:1b54b023fbbc174ea78aef6e3644c1f74f5b93e634d7e4bda486456bb3386791
+```
+
+## Discover
+
+Discovering artifacts of a certain type linking with the given artifact can be done with the command `oras discover`.
+
+For example, discover artifacts of type `application/vnd.cncf.notary.v2` linked with `localhost:5000/test:latest` (digests are also accepted):
+
+```
+oras discover --artifact-type application/vnd.cncf.notary.v2 \
+    localhost:5000/test:latest
+```
+
+The output is
+
+```
+Discovered 1 artifacts referencing localhost:5000/test:latest
+Digest: sha256:c38fe4b80a6c5c23b211365408bdb8deeda5132cd802c988fb4cd0b972ccfb9f
+Reference: application/vnd.cncf.notary.v2
+- sha256:556ec1d63c2153fc9645c6af2d87b0ebe66d356457d95d7cce4617aa9f9ec27f
+```

docs/push_adv.md

@@ -0,0 +1,81 @@
+# Advanced Push
+
+This documentation explains how advanced push operations can be done with `oras push` CLI.
+
+## Pushing without Tagging
+
+Pushing by digest is the default behavior if a tag is not provided.
+
+```
+$ oras push localhost:5000/test hello.txt
+Uploading a948904f2f0f hello.txt
+Pushed localhost:5000/test
+Digest: sha256:c38fe4b80a6c5c23b211365408bdb8deeda5132cd802c988fb4cd0b972ccfb9f
+$ rm hello.txt
+$ oras pull localhost:5000/test@sha256:c38fe4b80a6c5c23b211365408bdb8deeda5132cd802c988fb4cd0b972ccfb9f
+Downloaded a948904f2f0f hello.txt
+Pulled localhost:5000/test@sha256:c38fe4b80a6c5c23b211365408bdb8deeda5132cd802c988fb4cd0b972ccfb9f
+Digest: sha256:c38fe4b80a6c5c23b211365408bdb8deeda5132cd802c988fb4cd0b972ccfb9f
+```
+
+## Dry Run
+
+It is possible to push artifacts in `dry-run` mode by specifying `--dry-run` option.
+
+```
+$ oras push localhost:5000/test:latest hello.txt --dry-run
+Entered dry-run mode
+Uploading a948904f2f0f hello.txt
+Pushed localhost:5000/test:latest
+Digest: sha256:c38fe4b80a6c5c23b211365408bdb8deeda5132cd802c988fb4cd0b972ccfb9f
+```
+
+In `dry-run` mode, everything is computed except sending anything to the actual remote server.
+
+## Export Manifest
+
+The pushed manifest is useful in some scenarios such as signing.
+To export the manifest pushed to the remote, a target file name is required to be specified by the `--export-manifest` option in order to save the exported manifest.
+
+For example:
+
+```
+$ oras push localhost:5000/test:latest hello.txt --export-manifest manifest.json
+Uploading a948904f2f0f hello.txt
+Pushed localhost:5000/test:latest
+Digest: sha256:c38fe4b80a6c5c23b211365408bdb8deeda5132cd802c988fb4cd0b972ccfb9f
+```
+
+After that,  `cat manifest.json | jq .` outputs
+
+```json
+{
+  "schemaVersion": 2,
+  "config": {
+    "mediaType": "application/vnd.unknown.config.v1+json",
+    "digest": "sha256:44136fa355b3678a1146ad16f7e8649e94fb4fc21fe77e8310c060f61caaff8a",
+    "size": 2
+  },
+  "layers": [
+    {
+      "mediaType": "application/vnd.oci.image.layer.v1.tar",
+      "digest": "sha256:a948904f2f0f479b8f8197694b30184b0d2ed1c1cd2a1ec0fb85d299a192a447",
+      "size": 12,
+      "annotations": {
+        "org.opencontainers.image.title": "hello.txt"
+      }
+    }
+  ]
+}
+```
+
+Combined with the dry-run mode, it is possible to export the manifest without pushing to the remote.
+
+```
+$ oras push localhost:5000/test:latest hello.txt --export-manifest exported-manifest.json --dry-run
+Entered dry-run mode
+Uploading a948904f2f0f hello.txt
+Pushed localhost:5000/test:latest
+Digest: sha256:c38fe4b80a6c5c23b211365408bdb8deeda5132cd802c988fb4cd0b972ccfb9f
+```
+