Skip to content

docs: improve formatted output for oras discover#1625

Merged
Wwwsylvia merged 13 commits into
oras-project:mainfrom
FeynmanZhou:discover-output
Mar 25, 2025
Merged

docs: improve formatted output for oras discover#1625
Wwwsylvia merged 13 commits into
oras-project:mainfrom
FeynmanZhou:discover-output

Conversation

@FeynmanZhou

@FeynmanZhou FeynmanZhou commented Feb 18, 2025 •
edited
Loading

Copy link
Copy Markdown
Member

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 enable users to show the manifest content of the subject image and all referrers in multiple formats.

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:

  • Does the affected code have corresponding tests, e.g. unit test, E2E test?
  • Does this change require a documentation update?
  • Does this introduce breaking changes that would require an announcement or bumping the major version?
  • Do all new files have an appropriate license header?

@codecov

codecov Bot commented Feb 18, 2025 •
edited
Loading

Copy link
Copy Markdown

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 84.52%. Comparing base (756d60f) to head (452ec63).
Report is 1 commits behind head on main.

Additional details and impacted files 
@@           Coverage Diff           @@
##             main    #1625   +/-   ##
=======================================
  Coverage   84.52%   84.52%           
=======================================
  Files         126      126           
  Lines        5681     5681           
=======================================
  Hits         4802     4802           
  Misses        625      625           
  Partials      254      254

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

sajayantony
sajayantony reviewed Feb 19, 2025
View reviewed changes
Comment thread docs/proposals/formatted-output.md Outdated
shizhMSFT
shizhMSFT reviewed Feb 19, 2025
View reviewed changes
Comment thread docs/proposals/formatted-output.md Outdated
shizhMSFT
shizhMSFT reviewed Feb 19, 2025
View reviewed changes
Comment thread docs/proposals/formatted-output.md
Comment thread docs/proposals/formatted-output.md Outdated
sajayantony
sajayantony reviewed Feb 19, 2025
View reviewed changes
Comment thread docs/proposals/formatted-output.md Outdated
shizhMSFT
shizhMSFT reviewed Feb 19, 2025
View reviewed changes
Comment thread docs/proposals/formatted-output.md Outdated
yizha1
yizha1 reviewed Feb 19, 2025
View reviewed changes
Comment thread docs/proposals/formatted-output.md Outdated
@FeynmanZhou

FeynmanZhou commented Feb 19, 2025 •
edited
Loading

Copy link
Copy Markdown
Member Author

Based on the community discussion on Feb 18, @oras-project/oras-cli ORAS maintainers agreed on these things:

  • Show root image and its all referrers in the JSON output by default. This ensures data consistency among other data format output (e.g. tree, table)
  • Use referrers as the field name in the top-level and second-level referrers, instead of manifests
  • Show the referrers with full depth by default, introduce a flag --depth to allow users to limit the maximum depth of referrers in the formatted output.
  • Use JSON Schema and text to list the fields in formatted output

@shizhMSFT shizhMSFT changed the title doc: improve formatted output for oras discover docs: improve formatted output for oras discover Feb 19, 2025
@FeynmanZhou FeynmanZhou requested a review from Copilot March 6, 2025 07:59
Copilot AI reviewed Mar 6, 2025
View reviewed changes

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

PR Overview

This PR enhances the documentation for the formatted output of the oras discover command, aiming to clearly present both the subject image and its associated referrers' manifests in tree view and JSON output formats.

  • Clarifies the description of the referrers' manifest output.
  • Adds examples for recursive tree view and pretty JSON output.
  • Updates field descriptions in the formatted output documentation.

Reviewed Changes

File Description
docs/proposals/formatted-output.md Updates and additions to improve clarity and formatting for oras discover output

Copilot reviewed 1 out of 1 changed files in this pull request and generated 1 comment.

Comment thread docs/proposals/formatted-output.md Outdated
@wangxiaoxuan273 wangxiaoxuan273 mentioned this pull request Mar 7, 2025
Closed
1 task
Copilot AI reviewed Mar 7, 2025
View reviewed changes

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

PR Overview

This PR improves the formatted output for oras discover by updating field names and adding recursive output examples and a new depth flag.

  • Renames the "manifests" field to "referrers" for consistency.
  • Adds detailed examples for JSON, tree, and table outputs with recursive referrers.
  • Introduces the --depth flag to control the recursion depth of referrers.

Reviewed Changes

File Description
docs/proposals/formatted-output.md Updates documentation to improve output format examples and details

Copilot reviewed 1 out of 1 changed files in this pull request and generated no comments.

@wangxiaoxuan273

wangxiaoxuan273 commented Mar 10, 2025

Copy link
Copy Markdown
Contributor

Based on the community discussion on Feb 18, @oras-project/oras-cli ORAS maintainers agreed on these things:

  • Show root image and its all referrers in the JSON output by default. This ensures data consistency among other data format output (e.g. tree, table)
  • Use referrers as the field name in the top-level and second-level referrers, instead of manifests
  • Show the referrers with full depth by default, introduce a flag --depth to allow users to limit the maximum depth of referrers in the formatted output.
  • Use JSON Schema and text to list the fields in formatted output

Based on the offline discussion on March 7, the following conclusions have been reached:

  • Table view of oras discover will be deprecated.
  • Timeout will not be introduced as we don't see valid scenarios for it.

wangxiaoxuan273
wangxiaoxuan273 reviewed Mar 10, 2025
View reviewed changes
Comment thread docs/proposals/formatted-output.md Outdated
@wangxiaoxuan273 wangxiaoxuan273 mentioned this pull request Mar 10, 2025
Merged
4 tasks
wangxiaoxuan273
wangxiaoxuan273 reviewed Mar 13, 2025
View reviewed changes
Comment thread docs/proposals/formatted-output.md
@wangxiaoxuan273 wangxiaoxuan273 mentioned this pull request Mar 13, 2025
Merged
4 tasks
TerryHowe
TerryHowe reviewed Mar 19, 2025
View reviewed changes

@TerryHowe TerryHowe left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The current unresolved comments should be addressed, but generally looks good

Wwwsylvia
Wwwsylvia approved these changes Mar 20, 2025
View reviewed changes

@Wwwsylvia Wwwsylvia left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM with nit

Comment thread docs/proposals/formatted-output.md Outdated
TerryHowe
TerryHowe approved these changes Mar 21, 2025
View reviewed changes

@TerryHowe TerryHowe left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

/lgtm

Wwwsylvia
Wwwsylvia approved these changes Mar 24, 2025
View reviewed changes

@Wwwsylvia Wwwsylvia left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM

shizhMSFT
shizhMSFT approved these changes Mar 24, 2025
View reviewed changes

@shizhMSFT shizhMSFT left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM

@FeynmanZhou FeynmanZhou force-pushed the discover-output branch 3 times, most recently from 321d63d to f2e73e7 Compare March 25, 2025 01:30
@FeynmanZhou
doc: improve formatted output for oras discover
facea91 
Signed-off-by: feynmanzhou <feynmanzhou@microsoft.com>
@FeynmanZhou
doc: improve formatted output for oras discover
43ae027 
Signed-off-by: feynmanzhou <feynmanzhou@microsoft.com>
@FeynmanZhou
resolve comments and refine spec based on the discussion
608b4cf 
Signed-off-by: Feynman Zhou <feynmanzhou@microsoft.com>
@FeynmanZhou
resolve comments and refine spec based on the discussion
ada4407 
Signed-off-by: Feynman Zhou <feynmanzhou@microsoft.com>
@FeynmanZhou
resolve comments
5f27baa 
Signed-off-by: Feynman Zhou <feynmanzhou@microsoft.com>
@FeynmanZhou
add deprecation of table view
25e6ef8 
Signed-off-by: Feynman Zhou <feynmanzhou@microsoft.com>
@FeynmanZhou
update spec
93baca7 
Signed-off-by: Feynman Zhou <feynmanzhou@microsoft.com>
@FeynmanZhou
resolve comments and add JSON schema for JSON output
5d0fd56 
Signed-off-by: Feynman Zhou <feynmanzhou@microsoft.com>
@FeynmanZhou
resolve comments
747d307 
Signed-off-by: Feynman Zhou <feynmanzhou@microsoft.com>
@FeynmanZhou
resolve comments
cf31a19 
Signed-off-by: Feynman Zhou <feynmanzhou@microsoft.com>
@FeynmanZhou
resolve comments
d829839 
Signed-off-by: Feynman Zhou <feynmanzhou@microsoft.com>
@FeynmanZhou
refine the spec
b9b6679 
Signed-off-by: Feynman Zhou <feynmanzhou@microsoft.com>
@FeynmanZhou

FeynmanZhou commented Mar 25, 2025

Copy link
Copy Markdown
Member Author

Hi @oras-project/oras-cli , I've rebased the branch. Now it should be ready to merge. Thanks.

@FeynmanZhou
resolve a missing git commit
452ec63 
Signed-off-by: Feynman Zhou <feynmanzhou@microsoft.com>
Wwwsylvia
Wwwsylvia approved these changes Mar 25, 2025
View reviewed changes

@Wwwsylvia Wwwsylvia left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM

@Wwwsylvia Wwwsylvia merged commit a3f3230 into oras-project:main Mar 25, 2025
@Wwwsylvia Wwwsylvia mentioned this pull request Apr 24, 2025
Merged
6 tasks
@mmalina mmalina mentioned this pull request Aug 21, 2025
Merged
1 task
@Wwwsylvia Wwwsylvia mentioned this pull request Sep 3, 2025
Merged
6 tasks
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

Copilot code review Copilot Copilot left review comments

@TerryHowe TerryHowe TerryHowe approved these changes

@Wwwsylvia Wwwsylvia Wwwsylvia approved these changes

@shizhMSFT shizhMSFT shizhMSFT approved these changes

@SteveLasker SteveLasker Awaiting requested review from SteveLasker

@qweeah qweeah Awaiting requested review from qweeah

@sajayantony sajayantony Awaiting requested review from sajayantony sajayantony is a code owner

@yizha1 yizha1 Awaiting requested review from yizha1

+1 more reviewer

@wangxiaoxuan273 wangxiaoxuan273 wangxiaoxuan273 approved these changes

Reviewers whose approvals may not affect merge requirements

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

Oras Discover - json output include details of the image itself and not just directly attached artifacts (option for all artifacts)

8 participants

@FeynmanZhou @wangxiaoxuan273 @TerryHowe @sajayantony @Wwwsylvia @shizhMSFT @yizha1