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 #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]

Codecov Report

All modified and coverable lines are covered by tests ✅

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              

☔ 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]

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 

[shizhMSFT]

Nice summary on the scenarios. They can be summarized as the following two types of scenarios:

1. Propagation (cascading updates)
2. Individual updates

[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

[Copilot]

Pull Request Overview

A proposal document introducing scenarios for attaching files (e.g., EoL annotations) to multi-platform images via the ORAS CLI.

• Adds a new markdown file outlining upward and downward annotation propagation scenarios.
• Describes example workflows for marking outdated platform-specific and multi-platform images.
• Illustrates current limitations and manual steps required with oras attach.

Comments suppressed due to low confidence (1)

docs/proposals/oras-attach-multi-platform.md:37

• There's a missing 'to' in 'she has execute'; it should read 'she has to execute multiple commands.'

Alice has to manually retrieve the new digests and run `oras attach` twice: once for the old digest of the parent image index and once for the platform-specific image. If multiple platform-specific images require updates, she has execute multiple commands.

[Wwwsylvia]

nit: I think it might be a bit abrupt to set the environment variables here without using them immediately. Should we move this section downward to be closer to the oras attach commands that utilize these variables?

[Wwwsylvia]

In the diagram, it's not clear that which on is a1a1 and which one is b1b1.

[Wwwsylvia]

nit: So b1b1 now becomes r1r1 and a1a1 now becomes z1z1? Does it mean that the image tags are updated after the images are patched? It might be strange as tags are usually reused while digests change.
Would it be better to use demo/alpine@sha256:a1a1 to represent the images?

[Wwwsylvia]

What's the difference between scenario A and B? It looks like it's the same that some platform-specific images are vulnerable and the affected index needs to be patched as well? 🤔

[FeynmanZhou]

Close this PR as the corresponding issue #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 #1741 #1531 in my new proposal. cc @Wwwsylvia