Skip to content

Commit cf4a66f

Browse files
committed
chore: clarify VersionOrAliasName and make clear ctf impl is optional
On-behalf-of: SAP <matthias.bruns@sap.com> Signed-off-by: Matthias Bruns <git@matthiasbruns.com>
1 parent adddd5a commit cf4a66f

3 files changed

Lines changed: 13 additions & 17 deletions

File tree

doc/03-persistence/01-operations.md

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -100,9 +100,9 @@ that resolves to exactly one component version at any point in time. Alias names
100100

101101
- **`AddComponentVersionAlias(ComponentId, VersionOrAliasName, AliasName) error`**
102102

103-
Attach a symbolic alias to an existing component version (or to another alias, enabling
104-
alias chains). `AliasName` **MUST NOT** be a valid OCM version string. If the alias
105-
already exists it is updated to point to the new target.
103+
Attach a symbolic alias to an existing component version. `VersionOrAliasName` is either
104+
a version or an existing alias; `AliasName` **MUST NOT** be a valid OCM version string.
105+
If the alias already exists it is updated to point to the new target.
106106

107107
- **`RemoveComponentVersionAlias(ComponentId, AliasName) error`**
108108

doc/04-extensions/03-storage-backends/ctf.md

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -57,13 +57,14 @@ Local blobs are always stored as blobs.
5757

5858
## Alias Management Operations
5959

60-
CTF archives support the optional version alias operations defined in
60+
CTF archives **MAY** implement the optional version alias operations defined in
6161
[Version Alias Operations](../../../doc/03-persistence/01-operations.md#version-alias-operations).
62+
The following describes how each operation maps onto the CTF artifact index.
6263

6364
**`AddComponentVersionAlias`**
6465

65-
The alias is recorded in `artifact-index.json` as a tag pointing to the same digest as the
66-
target component version. If the tag already exists it **MUST** be updated to point to the
66+
The alias is recorded in `artifact-index.json` as a tag pointing to the same digest as
67+
`VersionOrAliasName` (a version or existing alias). If the tag already exists it **MUST** be updated to point to the
6768
new digest. `AliasName` **MUST NOT** be a valid OCM version string.
6869

6970
**`RemoveComponentVersionAlias`**

doc/04-extensions/03-storage-backends/oci.md

Lines changed: 6 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -864,21 +864,16 @@ are implemented against an OCI registry.
864864

865865
**`AddComponentVersionAlias`**
866866

867-
Implementations **MUST** resolve `VersionOrAliasName` as an OCI tag or digest in the
868-
component's repository, validate that the resolved descriptor represents a valid OCM
869-
component version, and then push the alias as an OCI tag pointing to that descriptor
870-
using the [OCI Distribution Specification manifest push](https://github.com/opencontainers/distribution-spec/blob/v1.1.1/spec.md#pushing-manifests)
867+
Implementations **MUST** resolve `VersionOrAliasName` (a version or existing alias) as an OCI tag in the component's
868+
repository, validate that the resolved descriptor represents a valid OCM component version,
869+
and then push the alias as an OCI tag pointing to that descriptor using the
870+
[OCI Distribution Specification manifest push](https://github.com/opencontainers/distribution-spec/blob/v1.1.1/spec.md#pushing-manifests)
871871
mechanism.
872872

873873
`AliasName` **MUST** be rejected if it is a valid OCM version string.
874874

875-
Because `VersionOrAliasName` **MAY** itself be a non-version alias, implementations
876-
**MUST** accept non-semver names there and resolve them to their underlying descriptor
877-
before tagging. This enables alias chains: e.g., pointing `edge` to wherever `latest`
878-
currently resolves.
879-
880-
After a successful push the alias tag in the registry **MUST** resolve to the descriptor
881-
identified by `VersionOrAliasName`. If the tag already pointed elsewhere it is overwritten.
875+
After a successful push the alias tag **MUST** resolve to the descriptor identified by
876+
`VersionOrAliasName`. If the tag already pointed elsewhere it is overwritten.
882877

883878
**`RemoveComponentVersionAlias`**
884879

0 commit comments

Comments
 (0)