docs: improve formatted output for oras discover #1625
Conversation
Signed-off-by: feynmanzhou <[email protected]>
FeynmanZhou
requested review from
sajayantony,
shizhMSFT,
SteveLasker,
qweeah,
Wwwsylvia and
TerryHowe
as code owners
Codecov ReportAll modified and coverable lines are covered by tests ✅
Additional details and impacted files@@ Coverage Diff @@
## main #1625 +/- ##
==========================================
- Coverage 84.41% 84.37% -0.04%
==========================================
Files 120 120
Lines 5460 5460
==========================================
- Hits 4609 4607 -2
- Misses 604 606 +2
Partials 247 247 ☔ View full report in Codecov by Sentry. |
Signed-off-by: feynmanzhou <[email protected]>
| - `size`: referrer file size in bytes | ||
| - `artifactType`: artifact type of a referrer | ||
| - `annotations`: contains arbitrary metadata in a referrer | ||
| - `referrerManifests`: the list of referrers' manifest |
There was a problem hiding this comment.
What about manifests or referrers basically the schema type is the type of the root object.
There was a problem hiding this comment.
In terms of consistency, manifests actually makes more sense as the schema is the same, just that users may not understand what does "manifests" mean. Maybe we should have called the root manifests referrers in the first place😂...
There was a problem hiding this comment.
We will use referrers as the field name in those two places based on the community discussion.
| - `size`: referrer file size in bytes | ||
| - `artifactType`: artifact type of a referrer | ||
| - `annotations`: contains arbitrary metadata in a referrer | ||
| - `referrerManifests`: the list of referrers' manifest |
There was a problem hiding this comment.
What if this field becomes a field of the manifest?
There was a problem hiding this comment.
Yes the ORAS manifest output schema can have an optional referrers which is a self referencing type.
| oras discover localhost:5000/kubernetes/kubectl@sha256:bece4f4746a39cb39e38451c70fa5a1e5ea4fa20d4cca40136b51d9557918b01 --format json --recursive | ||
| ``` | ||
|
|
||
| ``` |
There was a problem hiding this comment.
nit: this code block is not a valid json
| - `annotations`: contains arbitrary metadata in a referrer | ||
| - `referrerManifests`: the list of referrers' manifest | ||
|
|
||
| For example, when there are two refferers lifecycle metadata and in-toto attestation associated with a sample image, the signatures are associated with these two files respectively. The output in a tree view will be: |
There was a problem hiding this comment.
There are typos: refferers --> referrers.
| When showing the subject image and all referrers' manifests recursively in a pretty JSON output, the following JSON output should be returned: | ||
|
|
||
| ```bash | ||
| oras discover localhost:5000/kubernetes/kubectl@sha256:bece4f4746a39cb39e38451c70fa5a1e5ea4fa20d4cca40136b51d9557918b01 --format json --recursive |
There was a problem hiding this comment.
+1 to @Wwwsylvia's comment - --recursive is default (true) in tree and not in -format json sounds ood.
flag defaults changing depending on output formats seems really odd.
| When showing the subject image and all referrers' manifests recursively in a pretty JSON output, the following JSON output should be returned: | ||
|
|
||
| ```bash | ||
| oras discover localhost:5000/kubernetes/kubectl@sha256:bece4f4746a39cb39e38451c70fa5a1e5ea4fa20d4cca40136b51d9557918b01 --format json --recursive |
There was a problem hiding this comment.
As @Wwwsylvia pointed out, the --recursive flag is newly introduced and may be inconsistent for other formats.
There was a problem hiding this comment.
Instead, we can introduce a --depth flag.
| When showing the subject image and all referrers' manifests recursively in a pretty JSON output, the following JSON output should be returned: | ||
|
|
||
| ```bash | ||
| oras discover localhost:5000/kubernetes/kubectl@sha256:bece4f4746a39cb39e38451c70fa5a1e5ea4fa20d4cca40136b51d9557918b01 --format json --recursive |
There was a problem hiding this comment.
Is there a need to set a limit on the recursive depth?
|
Based on the community discussion on Feb 18, @oras-project/oras-cli ORAS maintainers agreed on these things:
|
shizhMSFT
changed the title
What this PR does / why we need it:
This PR improves formatted output for
oras discover. For example, if the referrers have associated referrers, ORAS should be able to show the manifest content of the subject image and all referrers.Which issue(s) this PR fixes (optional, in
fixes #<issue number>(, fixes #<issue_number>, ...)format, will close the issue(s) when PR gets merged):Fixes #1403
Please check the following list: