Skip to content

docs: add usage scenarios for oras-go library - #1107

Draft
TerryHowe wants to merge 13 commits into
oras-project:mainfrom
TerryHowe:docs/scenarios
Draft

docs: add usage scenarios for oras-go library#1107
TerryHowe wants to merge 13 commits into
oras-project:mainfrom
TerryHowe:docs/scenarios

Conversation

@TerryHowe

@TerryHowe TerryHowe commented Mar 3, 2026

Copy link
Copy Markdown
Member

Summary

  • Adds docs/SCENARIOS.md documenting 10 usage scenarios for the oras-go library
  • Covers: full config stack, CLI tool with flag overrides, policy enforcement, artifact distribution, object-oriented artifacts, registry mirroring, OCI local storage, credential management, signature verification, and library middleware
  • Includes configuration loading options (LoadConfigs, LoadConfigsWithOptions, direct construction)
  • Includes summary matrix mapping scenarios to packages and features

Test plan

  • Verify code examples are consistent with current API surface
  • Review scenario descriptions for accuracy and completeness

@codecov

codecov Bot commented Mar 3, 2026 •
edited
Loading

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 84.75%. Comparing base (4d7b803) to head (db397a0).
⚠️ Report is 9 commits behind head on main.

Additional details and impacted files 
@@            Coverage Diff             @@
##             main    #1107      +/-   ##
==========================================
+ Coverage   84.26%   84.75%   +0.48%     
==========================================
  Files          93       94       +1     
  Lines        7101     7306     +205     
==========================================
+ Hits         5984     6192     +208     
+ Misses        689      676      -13     
- Partials      428      438      +10

☔ View full report in Codecov by Harness.
📢 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.

sabre1041
sabre1041 previously requested changes Mar 8, 2026
View reviewed changes

@sabre1041 sabre1041 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.

This looks really good @TerryHowe ! Thanks for compiling these scenarios. A few suggestions

Comment thread docs/SCENARIOS.md Outdated
Comment thread docs/SCENARIOS.md
Comment thread docs/SCENARIOS.md Outdated
Comment thread docs/SCENARIOS.md Outdated
Comment thread docs/SCENARIOS.md Outdated
Comment thread docs/SCENARIOS.md
Comment thread docs/SCENARIOS.md
Comment thread docs/SCENARIOS.md Outdated
Comment thread docs/SCENARIOS.md Outdated
Comment thread docs/SCENARIOS.md Outdated
TerryHowe added a commit to TerryHowe/oras-go that referenced this pull request Mar 9, 2026
@TerryHowe
license: add Apache 2.0 headers to functional test files
0064b6b 
docs(scenarios): apply review feedback and add new scenarios

- Add ORAS Apache 2.0 license headers to all 11 functional test files
- Apply Andrew's review comments from oras-project#1107:
  - "targeted for contributors" (was "intended for")
  - "Utilizes custom CA certificates" (was "Picks up")
  - "set is used instead of the default for that config type"
  - containers-policy.json lowercase
  - Add flag.Bool/flag.String declarations to CLI scenario
  - "config-file credentials are used automatically otherwise"
  - "enforce trust decisions before pulling images"
  - Explain what scope is in policy scenario
  - Explain sbomLayers and payload in code examples
  - Add intro paragraph to Multi-Platform Images subsection
  - Add backticks around objects package name
  - Fix air-gapped bullet punctuation
- Add new scenarios: Referrers (#14) and Structured Error Handling (#15)
- Update Scenario 6 (Mirroring) with ExtendedCopy for referrers
- Update Scenario 11 (Middleware) with NewWarningLogger
- Update Scenario 4 (Artifact Distribution) with TagBytes/TagBytesN
- Update Summary Matrix with new scenarios

Signed-off-by: Terry Howe <terrylhowe@gmail.com>
@TerryHowe
TerryHowe requested a review from sabre1041 March 9, 2026 13:20
TerryHowe added a commit to TerryHowe/oras-go that referenced this pull request Mar 9, 2026
@TerryHowe
license: add Apache 2.0 headers to functional test files
bfff613 
docs(scenarios): apply review feedback and add new scenarios

- Add ORAS Apache 2.0 license headers to all 11 functional test files
- Apply Andrew's review comments from oras-project#1107:
  - "targeted for contributors" (was "intended for")
  - "Utilizes custom CA certificates" (was "Picks up")
  - "set is used instead of the default for that config type"
  - containers-policy.json lowercase
  - Add flag.Bool/flag.String declarations to CLI scenario
  - "config-file credentials are used automatically otherwise"
  - "enforce trust decisions before pulling images"
  - Explain what scope is in policy scenario
  - Explain sbomLayers and payload in code examples
  - Add intro paragraph to Multi-Platform Images subsection
  - Add backticks around objects package name
  - Fix air-gapped bullet punctuation
- Add new scenarios: Referrers (#14) and Structured Error Handling (#15)
- Update Scenario 6 (Mirroring) with ExtendedCopy for referrers
- Update Scenario 11 (Middleware) with NewWarningLogger
- Update Scenario 4 (Artifact Distribution) with TagBytes/TagBytesN
- Update Summary Matrix with new scenarios

Signed-off-by: Terry Howe <terrylhowe@gmail.com>
FeynmanZhou
FeynmanZhou reviewed Mar 18, 2026
View reviewed changes
Comment thread docs/SCENARIOS.md
TerryHowe added a commit to TerryHowe/oras-go that referenced this pull request Mar 31, 2026
@TerryHowe
license: add Apache 2.0 headers to functional test files
4a1566c 
docs(scenarios): apply review feedback and add new scenarios

- Add ORAS Apache 2.0 license headers to all 11 functional test files
- Apply Andrew's review comments from oras-project#1107:
  - "targeted for contributors" (was "intended for")
  - "Utilizes custom CA certificates" (was "Picks up")
  - "set is used instead of the default for that config type"
  - containers-policy.json lowercase
  - Add flag.Bool/flag.String declarations to CLI scenario
  - "config-file credentials are used automatically otherwise"
  - "enforce trust decisions before pulling images"
  - Explain what scope is in policy scenario
  - Explain sbomLayers and payload in code examples
  - Add intro paragraph to Multi-Platform Images subsection
  - Add backticks around objects package name
  - Fix air-gapped bullet punctuation
- Add new scenarios: Referrers (#14) and Structured Error Handling (#15)
- Update Scenario 6 (Mirroring) with ExtendedCopy for referrers
- Update Scenario 11 (Middleware) with NewWarningLogger
- Update Scenario 4 (Artifact Distribution) with TagBytes/TagBytesN
- Update Summary Matrix with new scenarios

Signed-off-by: Terry Howe <terrylhowe@gmail.com>
TerryHowe added a commit to TerryHowe/oras-go that referenced this pull request Mar 31, 2026
@TerryHowe
license: add Apache 2.0 headers to functional test files
d77723d 
docs(scenarios): apply review feedback and add new scenarios

- Add ORAS Apache 2.0 license headers to all 11 functional test files
- Apply Andrew's review comments from oras-project#1107:
  - "targeted for contributors" (was "intended for")
  - "Utilizes custom CA certificates" (was "Picks up")
  - "set is used instead of the default for that config type"
  - containers-policy.json lowercase
  - Add flag.Bool/flag.String declarations to CLI scenario
  - "config-file credentials are used automatically otherwise"
  - "enforce trust decisions before pulling images"
  - Explain what scope is in policy scenario
  - Explain sbomLayers and payload in code examples
  - Add intro paragraph to Multi-Platform Images subsection
  - Add backticks around objects package name
  - Fix air-gapped bullet punctuation
- Add new scenarios: Referrers (#14) and Structured Error Handling (#15)
- Update Scenario 6 (Mirroring) with ExtendedCopy for referrers
- Update Scenario 11 (Middleware) with NewWarningLogger
- Update Scenario 4 (Artifact Distribution) with TagBytes/TagBytesN
- Update Summary Matrix with new scenarios

Signed-off-by: Terry Howe <terrylhowe@gmail.com>
TerryHowe added a commit to TerryHowe/oras-go that referenced this pull request Apr 1, 2026
@TerryHowe
license: add Apache 2.0 headers to functional test files
761c1dc 
docs(scenarios): apply review feedback and add new scenarios

- Add ORAS Apache 2.0 license headers to all 11 functional test files
- Apply Andrew's review comments from oras-project#1107:
  - "targeted for contributors" (was "intended for")
  - "Utilizes custom CA certificates" (was "Picks up")
  - "set is used instead of the default for that config type"
  - containers-policy.json lowercase
  - Add flag.Bool/flag.String declarations to CLI scenario
  - "config-file credentials are used automatically otherwise"
  - "enforce trust decisions before pulling images"
  - Explain what scope is in policy scenario
  - Explain sbomLayers and payload in code examples
  - Add intro paragraph to Multi-Platform Images subsection
  - Add backticks around objects package name
  - Fix air-gapped bullet punctuation
- Add new scenarios: Referrers (#14) and Structured Error Handling (#15)
- Update Scenario 6 (Mirroring) with ExtendedCopy for referrers
- Update Scenario 11 (Middleware) with NewWarningLogger
- Update Scenario 4 (Artifact Distribution) with TagBytes/TagBytesN
- Update Summary Matrix with new scenarios

Signed-off-by: Terry Howe <terrylhowe@gmail.com>
@TerryHowe TerryHowe added the v3 Things belongs to version 3.x label Apr 1, 2026
@TerryHowe TerryHowe added this to the v3.0.0 milestone May 24, 2026
@TerryHowe
TerryHowe force-pushed the docs/scenarios branch 2 times, most recently from e365f74 to 8489b15 Compare August 11, 2026 17:25
TerryHowe and others added 8 commits August 23, 2026 19:29
@TerryHowe
docs: add usage scenarios for oras-go library
05c8c90 
Signed-off-by: Terry Howe <terrylhowe@gmail.com>
@TerryHowe @sabre1041
Update docs/SCENARIOS.md
3f17fc6 
Co-authored-by: Andrew Block <andy.block@gmail.com>
Signed-off-by: Terry Howe <terrylhowe@gmail.com>
@TerryHowe @sabre1041
Update docs/SCENARIOS.md
97b80c4 
Co-authored-by: Andrew Block <andy.block@gmail.com>
Signed-off-by: Terry Howe <terrylhowe@gmail.com>
@TerryHowe @sabre1041
Update docs/SCENARIOS.md
e00b4b7 
Co-authored-by: Andrew Block <andy.block@gmail.com>
Signed-off-by: Terry Howe <terrylhowe@gmail.com>
@TerryHowe @sabre1041
Update docs/SCENARIOS.md
157d16a 
Co-authored-by: Andrew Block <andy.block@gmail.com>
Signed-off-by: Terry Howe <terrylhowe@gmail.com>
@TerryHowe
docs: address document comments
e8eebd0 
Signed-off-by: Terry Howe <terrylhowe@gmail.com>
@TerryHowe
docs: add glossary section to SCENARIOS.md
8c0e80b 
Add a glossary of ORAS and OCI terms at the end of the usage scenarios
document to help readers unfamiliar with the terminology

Signed-off-by: Terry Howe <thowe@nvidia.com>
@TerryHowe
docs: correct stale API references in SCENARIOS.md
9b2d5cd 
Three snippets named APIs that do not exist:

- evaluator.Evaluate is spelled IsImageAllowed on policy.Evaluator.
- remote.GetCredentialFunc was renamed remote.NewCredentialFunc.
- Two auth.Client literals set a Credential field; the field is
  CredentialFunc.

Verified the rest of the document by extracting every package-qualified
exported symbol from it and resolving each with go doc. The only remaining
unresolved names are remote.ClientBuilder, remote.NewClientBuilder, and
remote.NewRepositoryWithProperties, which are forward references to the
builder API under review.

Signed-off-by: Terry Howe <terrylhowe@gmail.com>
@TerryHowe

TerryHowe commented Aug 24, 2026

Copy link
Copy Markdown
Member Author

Refreshed: rebased onto current main (was 17 behind) and fixed stale API references.

I verified the whole document mechanically — extracted every package-qualified exported symbol from the snippets and resolved each with go doc against main. 70 symbols checked, 4 did not resolve, 3 of which were real bugs and are now fixed:

  • evaluator.Evaluate → evaluator.IsImageAllowed (the actual method on policy.Evaluator)
  • remote.GetCredentialFunc → remote.NewCredentialFunc (renamed; 3 occurrences)
  • two auth.Client literals set a Credential field; the field is CredentialFunc

The only names that still do not resolve are remote.ClientBuilder, remote.NewClientBuilder and remote.NewRepositoryWithProperties — forward references to the builder API in #1328. I left those as written rather than removing the sections, since #1328 is open; they will resolve once it merges. Flagging in case you would rather they come out until then.

@TerryHowe TerryHowe mentioned this pull request Aug 24, 2026
Closed
@TerryHowe
docs: fold v3 design notes into the docs PR
643ec62 
Consolidates the documentation-only changes into a single PR so they can be
reviewed together and thinned out in one place: adds
docs/design/signedby-tag-resolution.md and
docs/design/config-credentials-coupling.md, previously proposed separately.

The config-credentials note is the version that describes the design as a
proposal. A later revision on the v3 working branch marks it implemented, but
the shared configfile package it refers to has not landed on main yet, so that
wording would be inaccurate here.

Signed-off-by: Terry Howe <terrylhowe@gmail.com>
@TerryHowe TerryHowe mentioned this pull request Aug 24, 2026
Merged
@TerryHowe
docs: add the v3 registry design note
366c206 
Folds the last design document into this PR, so every documentation-only
change for v3 is in one place rather than spread across branches. This one had
no PR of its own and was riding along on the v3 working branch.

Takes the copy from that working branch rather than the older docs branch: it
is three weeks newer and tracks the implementation, including the referrers
capability state machine.

Corrects one package prefix while moving it. NewSignedByVerifierFromConfig
lives in signature, not config; it takes a config type as its argument, which
is presumably where the confusion came from. Checked the rest of the document
the same way as SCENARIOS.md, by resolving every package-qualified exported
symbol with go doc. The only names that do not resolve are auth.Credential,
which is a deliberate reference to the v2 location in the migration table, and
remote.NewClientBuilder and remote.NewRepositoryWithProperties, which are
forward references to the builder API in oras-project#1328.

Signed-off-by: Terry Howe <terrylhowe@gmail.com>
TerryHowe added a commit to TerryHowe/oras-go that referenced this pull request Aug 24, 2026
@TerryHowe
docs: drop the v3 design notes and scenarios from the working branch
c754cba 
All four documents are carried by oras-project#1107, which is where the documentation-only
changes are being reviewed and pruned. Keeping a second copy here only invites
the two to drift, and the copies had already started to: the version of the
config/credentials note on this branch marks the design implemented, while
oras-project#1107 carries the proposal wording that is accurate against main today.

That status update is not lost. It belongs with the refactor it describes and
is recorded on oras-project#1331, to be applied once that lands.

docs/ is now identical to main, and this branch is code only.

Signed-off-by: Terry Howe <terrylhowe@gmail.com>
@TerryHowe TerryHowe mentioned this pull request Aug 24, 2026
Closed
@TerryHowe
TerryHowe marked this pull request as draft August 24, 2026 21:55
@TerryHowe
docs: correct scenario examples against feat/everything
3854a99 
Compile-checked every Go snippet in SCENARIOS.md against the current
implementation. Three examples did not build and one behavioural
description did not match the code:

- Middleware example set HandleWarning on the composed repository, but
  Compose returns the registry.Repository interface, which has no
  Registry field. Configure the concrete *remote.Repository first.
  NewWarningLogger also takes (registry string, logger *slog.Logger).
- Structured error example read copyErr.Descriptor, which CopyError does
  not have. Report copyErr.Op instead.
- Default retry behaviour listed a 30 s backoff cap and a 500/502/503/504
  status set, and claimed connection-refused and EOF are retried. The
  actual DefaultPolicy clamps to 3 s, retries 408 plus any 5xx, and only
  retries net.Error timeouts.

Also note that Configs.CredentialStore errors when no credential config
was loaded, unlike LoadConfigs which succeeds with no files present.

Claude-Session: https://claude.ai/code/session_019PbKUcjYUjfNDqCv5LoBTK
Signed-off-by: Terry Howe <terrylhowe@gmail.com>
This was referenced Aug 26, 2026
Closed
Closed
@TerryHowe
docs: cover mirrors, token flow, and pagination limits
37d6995 
Add the feat/everything capabilities that SCENARIOS.md predated:

- Scenario 16, registry mirror fallback: how registries.conf mirrors are
  resolved onto a Repository, the read-only and first-success-wins
  semantics, why context errors stop the chain, and what pull-from-mirror
  restricts.
- Scenario 17, bearer token flow selection: TokenFlowDistribution for
  registries implementing only the distribution-spec token endpoint, set
  via the registries.conf token-flow key, properties, or a custom
  auth.TokenFetcher.
- Scenario 18, bounded listing: the RepositoryListMaxPages,
  TagListMaxPages, and ReferrerListMaxPages caps, the Repository over
  Registry over unlimited resolution order, and errdef.ErrTooManyPages.

Also document LoadConfigsOptions.Strategy under scenario 1, flagging
StrategyUAPI as experimental, and add the new scenarios to the summary
matrix plus a Mirror glossary entry.

Every Go snippet was compile-checked against the branch, and both
registries.conf examples were parsed through LoadRegistriesConfig and
NewRegistryProperties to confirm they produce the documented result.

Claude-Session: https://claude.ai/code/session_019PbKUcjYUjfNDqCv5LoBTK
Signed-off-by: Terry Howe <terrylhowe@gmail.com>
@TerryHowe
docs: add namespace-scoped authentication scenario
db397a0 
Covers authenticating against a namespace within a registry
(example.com/myspace) rather than only against a registry host, the
RegistryScope value it needs, and why the current host-only Login and
CredentialFunc cannot express it.

Marked as proposed and linked to oras-project#1348.

Claude-Session: https://claude.ai/code/session_012zypfdViujYeFqpxUXpZUD
Signed-off-by: Terry Howe <terrylhowe@gmail.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@FeynmanZhou FeynmanZhou FeynmanZhou left review comments
@shizhMSFT shizhMSFT Awaiting requested review from shizhMSFT shizhMSFT is a code owner
@Wwwsylvia Wwwsylvia Awaiting requested review from Wwwsylvia Wwwsylvia is a code owner
@sabre1041 sabre1041 Awaiting requested review from sabre1041 sabre1041 is a code owner

At least 1 approving review is required to merge this pull request.

Assignees

No one assigned

Labels

keep open v3 Things belongs to version 3.x

Projects

None yet

Milestone

v3.0.0

Development

Successfully merging this pull request may close these issues.

3 participants

@TerryHowe @sabre1041 @FeynmanZhou