doc: add scenario doc for attaching files to a multi-platform image

[FeynmanZhou]

What this PR does / why we need it:

Add a scenario doc for attaching files to a multi-platform image. We need to discuss and align on the scenarios first.

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 https://github.com/oras-project/oras/issues/1531

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[bot]]

Codecov Report

All modified and coverable lines are covered by tests :white_check_mark:

Project coverage is 85.20%. Comparing base (a008df7) to head (e6b0ece). Report is 5 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #1682      +/-   ##
==========================================
+ Coverage   85.13%   85.20%   +0.06%     
==========================================
  Files         129      129              
  Lines        5780     5780              
==========================================
+ Hits         4921     4925       +4     
+ Misses        613      609       -4     
  Partials      246      246              

:umbrella: View full report in Codecov by Sentry.
:loudspeaker: Have feedback on the report? Share it here.

:rocket: New features to boost your workflow:

• :snowflake: Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[sajayantony]

I am hoping we can expand this scenario - Enable users to attach the same annotations to multiple manifests or index. The scope then would be about providing a way to script or enable users to obtain an annotation set (entity/manifest or data) that can be used to attach it to either multiple manifests or images.

For e.g.

$manifest = $(oras manifest create --annotation ... --artifact type)
oras attach registry/repo:build-tag  --manifest-data $manifest
oras attach regisry/repo2:build-tag --manifest-data $manifest 
oras attach regisry/repo3:build-tag --platform linux/amd64 --manifest-data $manifest 

[Wwwsylvia]

I am hoping we can expand this scenario - Enable users to attach the same annotations to multiple manifests or index. The scope then would be about providing a way to script or enable users to obtain an annotation set (entity/manifest or data) that can be used to attach it to either multiple manifests or images.

For e.g.

$manifest = $(oras manifest create --annotation ... --artifact type)
oras attach registry/repo:build-tag  --manifest-data $manifest
oras attach regisry/repo2:build-tag --manifest-data $manifest 
oras attach regisry/repo3:build-tag --platform linux/amd64 --manifest-data $manifest 

@sajayantony How does --manifest-data work here?

[sajayantony]

Enabling oras to create some kind of temporary manifest that can be piped into commands was the idea.

@sajayantony How does --manifest-data work here?

For e.g. manifest data can be something like.

artifactType: application/sbom+json
annotations: 
   key1:value1

The remaining information like subject and created time etc. can be filled by attach

oras attach example.com/hello-world:latest --platform  linux/amd64 --manifest-data $manifest sbom.json
 oras attach  example.com/hello-world:latest  --platform  arm/amd64 --manifest-data $manifest sbom.json

oras attach example.com/hello-world-nightly:latest --platform  linux/amd64 --manifest-data $manifest sbom.json
oras attach  example.com/hello-world-nightly:latest   --platform  arm/amd64 --manifest-data $manifest sbom.json

Another option would be to enable annotation only but then I think enabling construction of these types is more generic.

For example. oras index create can also take these data structure to compose using annotations and/or artifacts.

[Wwwsylvia]

@sajayantony What would be the expected result of these oras attach command? Would they create a referrer manifest that contains artifact type "application/sbom+json" and annotations "key1:value1" provided from the --manifest-data?

If so, is it equivalent to supplying --artifact-type and --annotation directly via environment variables? Are there other common fields that can be shared between different referrer manifests, other than artifactType and annotations?

artifactType="application/sbom+json"
annotation="key1=value1"

oras attach example.com/hello-world:latest --platform  linux/amd64 --artifact-type $artifactType --annotation $annotation
oras attach example.com/hello-world:latest  --platform  arm/amd64 --artifact-type $artifactType --annotation $annotation

oras attach example.com/hello-world-nightly:latest --platform  linux/amd64 --artifact-type $artifactType --annotation $annotation
oras attach  example.com/hello-world-nightly:latest --platform  arm/amd64 --artifact-type $artifactType --annotation $annotation

[FeynmanZhou]

Close this PR as the corresponding issue https://github.com/oras-project/oras/issues/1531 has been moved to ORAS v1.4.0.

[TerryHowe]

Why is this closed just because of scheduling?

[FeynmanZhou]

@TerryHowe This doc does not cover the end-to-end scenarios of attaching referrers to an image index and listing them. I plan to refactor this doc and target resolving two issues https://github.com/oras-project/oras/issues/1741 https://github.com/oras-project/oras/issues/1531 in my new proposal. cc @Wwwsylvia