From 3efe0b5b25a99a46348d6e5ebf28d3f078e7f001 Mon Sep 17 00:00:00 2001 From: Nikolay Boshnakov Date: Thu, 23 May 2024 11:32:16 +0300 Subject: [PATCH 1/5] Cleaned up glossary --- doc/glossary.md | 114 ++++++++++++++++-------------------------------- 1 file changed, 38 insertions(+), 76 deletions(-) diff --git a/doc/glossary.md b/doc/glossary.md index 8e98db8..111b7f4 100644 --- a/doc/glossary.md +++ b/doc/glossary.md @@ -14,22 +14,19 @@ The operations an implementation of an [access method](#accmeth) has to support. ### [Access Method Type](04-extensions/02-access-types/README.md) -The type of an [access specification](#accspec) determining the formal procedure -to use to access the blob content of an [artifact](#artifact). +The type of an [access specification](#accspec) determining the formal procedure to use to access the blob content of an [artifact](#artifact). ### [Access Specification](01-model/07-extensions.md#access-specification) -The specification of the technical access path to the physical blob content of -An [artifact](#artifact). +The specification of the technical access path to the physical blob content of an [artifact](#artifact). ### [Aggregation](02-processing/01-references.md) -The ability of the Open Component Model to compose component versions -based on other component versions. +The ability of the Open Component Model to compose component versions based on other component versions. ### [Artifact](01-model/02-elements-toplevel.md#artifacts-resources-and-sources) -Some blob content described by a [component version](#component-version). +Blob content described by a [component version](#component-version). ### [Artifact Digest](02-processing/03-signing-process.md#determing-the-artifact-digests) @@ -37,26 +34,21 @@ The (logical) digest of an [artifact](#artifact). ### [Artifact Normalization](02-processing/06-artifact-normalization.md) -The transformation of a technical blob content of an [artifact](#artifact) depending -on its type into a serialization-agnostic digest. +The transformation of a technical blob content of an [artifact](#artifact) depending on its type into a serialization-agnostic digest. ### [Artifact Reference](02-processing/01-references.md#referencing) -A relative or absolute reference to an [artifact](#artifact) described by a -[component version](#compvers). +A relative or absolute reference to an [artifact](#artifact) described by a [component version](#compvers). ### [Artifact Type](01-model/02-elements-toplevel.md#artifact-types) -The formal type of an [artifact](#artifact) described by a -[component version](#compvers). The type implies the logical interpretation of -The artifact blob. +The formal type of an [artifact](#artifact) described by a [component version](#compvers). The type implies the logical interpretation of the artifact blob. ## C ### [Component](01-model/01-model.md#components-and-component-versions) -An abstract entity describing a dedicated usage context or -meaning for a provided piece of software. +An abstract entity describing a dedicated usage context or meaning for a provided piece of software. ### [Component Constructor](https://ocm.software/docs/getting-started/first-steps-with-ocm/#all-in-one) @@ -68,8 +60,7 @@ The formal description of a [component version](#compvers). ### [Component Descriptor Normalization](02-processing/05-component-descriptor-normalization.md) -The mapping of the elements of a [component descriptor](#compdesc) into an -immutable format containg only signature relevant information used to calculate a digest. +The mapping of the elements of a [component descriptor](#compdesc) into an immutable format containing only signature relevant information used to calculate a digest. ### [Component Identity](01-model/02-elements-toplevel.md#component-identity) @@ -81,9 +72,7 @@ An entity able to store and retrieve [component versions](#compvers). See also [ ### [Component Version](01-model/01-model.md#components-and-component-versions) -A dedicated version of a [component](#component) described by the Open Component Model -described by a [component descriptor](#compdesc) and retrievable from -A [component repository](#comprep). +A dedicated version of a [component](#component) described by the Open Component Model described by a [component descriptor](#compdesc) and retrievable from a [component repository](#comprep). ### [Component Version Digest](02-processing/05-component-descriptor-normalization.md#component-descriptor-normalization) @@ -95,8 +84,7 @@ The globally unique identity of a [component version](#compvers). ### [Component Version Reference](02-processing/01-references.md#referencing) -A reference to a [component versions](#compvers) in a component version to -describe an aggregation relationship. +A reference to a [component versions](#compvers) in a component version to describe an aggregation relationship. ## D @@ -108,14 +96,11 @@ See [artifact digest](#artdigest) or [component version digest](#compdigest). ### [Element Identity](./01-model/03-elements-sub.md#element-identity) -Similar to component identity, the element identity is composed by the fields `name` and `version`. -In additon to that sources, resources and references can have an [extraIdentity](#extraid) if required. +Similar to component identity, the element identity is composed by the fields `name` and `version`. In addition to that, sources, resources, and references can have an [extraIdentity](#extraid) if required. ### [Extension Point](./03-persistence/01-operations.md#abstract-operations-defined-by-the-open-component-model) -Parts of the [OCM](#ocm) specification, which may be extended by arbitrary -variations. The specification just defines the meaning, syntax and or functional -behaviour of such elements. +Parts of the [OCM](#ocm) specification, which may be extended by arbitrary variations. The specification just defines the meaning, syntax and or functional behavior of such elements. ### [Extra Identity](./01-model/03-elements-sub.md#element-identity) @@ -125,18 +110,17 @@ Additional parts of the identity of an [element](#elemid) of a [component versio ### [gitHub](./04-extensions/02-access-types/github.md) -[access method](#accmeth) used to access Git commits in a GitHub repository. +An [access method](#accmeth) used to access Git commits in a GitHub repository. ## H ### [helm](./04-extensions/02-access-types/helm.md) -[access method](#accmeth) used to access [Helm Charts](#helmchart) in a Helm repository. +An [access method](#accmeth) used to access [Helm Charts](#helmchart) in a Helm repository. ### Helm Chart -A set of files describing the deplyoment of a Kubernetes application using -The [Helm](https://helm.sh/) deployment mechanism. +A set of files describing the deployment of a Kubernetes application using the [Helm](https://helm.sh/) deployment mechanism. See [element identity](#elemid), [component identity](#compid), [component version identity](#compversid) @@ -150,17 +134,15 @@ See [element identity](#elemid), [component identity](#compid), [component versi ### [Labels](01-model/03-elements-sub.md#labels) -Arbitrary typed information snippets attached to [component versions](#compvers), -[artifacts](#artifact) and [references](#compref). +Arbitrary typed information snippets attached to [component versions](#compvers), [artifacts](#artifact), and [references](#compref). ### [localBlob](./04-extensions/02-access-types/localblob.md) -[access method](#accmeth) used to access blobs stored along with a component version. +An [access method](#accmeth) used to access blobs stored along with a component version. ### [Localization](./05-guidelines/02-contract.md#example-helm-deployment) -The process of adapting content delivered as [artifacts](#artifact) in a [component versions](#compvers) -to a local repository landscape in a target environment. +The process of adapting content delivered as [artifacts](#artifact) in a [component versions](#compvers) to a local repository landscape in a target environment. ## M @@ -170,72 +152,59 @@ The mapping of the [elements](01-model/02-elements-toplevel.md) of the Open Comp ### [Model-Tool Contract](./05-guidelines/02-contract.md) -The agreement between the Open Component Model and tools working with content -provided by [component versions](#compvers), which regulates the cooperation -between both. +The agreement between the Open Component Model and tools working with content provided by [component versions](#compvers), which regulates the cooperation between both. ## N ### [Normalization](02-processing/03-signing-process.md#signing-process-and-normalization) -The transformation which can be used to calculate an immutable digest for signing purposes along a transportation path. There are two normalization procedures, [artifact normalization](#artnorm) and -[component descriptor normalization](#compdescnorm). +The transformation which can be used to calculate an immutable digest for signing purposes along a transportation path. There are two normalization procedures, [artifact normalization](#artnorm) and [component descriptor normalization](#compdescnorm). ### [npm](./04-extensions/02-access-types/npm.md) -[access method](#accmeth) used to access NodeJS packages in an NPM repository. +An [access method](#accmeth) used to access NodeJS packages in an NPM repository. ## O ### [ociArtifact](./04-extensions/02-access-types/ociartifact.md) -[access method](#accmeth) used to access OCI artifacts stored in an OCI registry. +An [access method](#accmeth) used to access OCI artifacts stored in an OCI registry. ### [ociBlob](./04-extensions/02-access-types/ociblob.md) -[access method](#accmeth) used to access blobs stored in an OCI registry. +An [access method](#accmeth) used to access blobs stored in an OCI registry. ### [Open Component Model](../README.md) -A technology- and location-agnostic description model for software delivery -Artifacts with attached meta-data, providing environment-specific access -path to described [artifacts](#artifact). +A technology- and location-agnostic description model for software delivery artifacts with attached meta-data, providing environment-specific access path to described [artifacts](#artifact). ### Operations -See [repository operations](#repops), [access methods](#accmeth) and -[access method operations](#accmethops). +See [repository operations](#repops), [access methods](#accmeth), and [access method operations](#accmethops). ## P -### [Platform Convention](01-model/06-conventions.md#operating-system-and-cpu-architecture)) +### [Platform Convention](01-model/06-conventions.md#operating-system-and-cpu-architecture) -Using extra identities to express the assignment of an [artifact](#artifact) to a dedicated -execution platform. +Using extra identities to express the assignment of an [artifact](#artifact) to a dedicated execution platform. ## R ### Reference -A reference to an element of the component model, see [artifact reference](#artref) -or [component version reference](#compref) +A reference to an element of the component model, see [artifact reference](#artref) or [component version reference](#compref). ### [Relative Resource Refererences](02-processing/01-references.md#relative-artifact-references) -A reference to an [artifact](#artifact) described by a [component version](#compvers) relative to -A given component version exploiting the [aggregation feature](#aggregation) of the Open Component -Model. It is part of the [model-tool contract](#contract). +A reference to an [artifact](#artifact) described by a [component version](#compvers) relative to a given component version exploiting the [aggregation feature](#aggregation) of the Open Component Model. It is part of the [model-tool contract](#contract). ### [Repository Operations](03-persistence/01-operations.md#repository-operations) -Abstract operations that have to be provided by a language binding for a -[mapping](#mapping) of the [Open Component Model](#ocm) to a dedicated storage -technology. +Abstract operations that have to be provided by a language binding for a [mapping](#mapping) of the [Open Component Model](#ocm) to a dedicated storage technology. ### [Repository Type](./03-persistence/02-mappings.md#mappings-for-ocm-persistence) -The type of a [mapping](#mapping) of the [Open Component Model](#ocm) specification -to a storage technology. +The type of a [mapping](#mapping) of the [Open Component Model](#ocm) specification to a storage technology. ### [Resource](01-model/02-elements-toplevel.md#resources) @@ -245,33 +214,26 @@ A delivery artifact described by a [component version](#compvers). ### [Signature](02-processing/02-signing.md#signing) -A [component version](#compvers) may be signed by an authority, the signature as -result of such a signing process is stored along with the component version. +A [component version](#compvers) may be signed by an authority, the signature as result of such a signing process is stored along with the component version. ### [Source](01-model/02-elements-toplevel.md#sources) -An artifact described by a [component version](#compvers) containing sources -used to generate one or more of the described [resources](#resource). +An artifact described by a [component version](#compvers) containing sources used to generate one or more of the described [resources](#resource). ### Specification Format -A format definition for the specification of attributes for -dedicated variants of some [extension points](#ext). See [access methods](#accmeth), -[repository types](#repotype), and [labels](#labels). +A format definition for the specification of attributes for dedicated variants of some [extension points](#ext). See [access methods](#accmeth), [repository types](#repotype), and [labels](#labels). ### [s3](./04-extensions/02-access-types/s3.md) -[access method](#accmeth) used to access blobs in an S3 repository, a [mapping](#mapping) to store content in an S3 repository +An [access method](#accmeth) used to access blobs in an S3 repository, a [mapping](#mapping) to store content in an S3 repository ## T ### [Transport](05-guidelines/01-transport.md) -The operation on [component versions](#compvers) transferring content from -one OCM repository into another one. +The operation on [component versions](#compvers) transferring content from one OCM repository into another one. ### Type -A formal representation of the kind of an [extension point](#ext) of the -[Open Component Model](#ocm). See [repository type](#repotype), -[access method type](#acctype), [artifact type](#arttype) [label](#labels). +A formal representation of the kind of an [extension point](#ext) of the [Open Component Model](#ocm). See [repository type](#repotype), [access method type](#acctype), [artifact type](#arttype), [label](#labels). From 78809cfccbd69f6f3cead08b4ffd1516058e5429 Mon Sep 17 00:00:00 2001 From: Nikolay Boshnakov Date: Thu, 23 May 2024 11:32:41 +0300 Subject: [PATCH 2/5] Added OCM Coordinates term --- doc/glossary.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/doc/glossary.md b/doc/glossary.md index 111b7f4..da07649 100644 --- a/doc/glossary.md +++ b/doc/glossary.md @@ -178,6 +178,10 @@ An [access method](#accmeth) used to access blobs stored in an OCI registry. A technology- and location-agnostic description model for software delivery artifacts with attached meta-data, providing environment-specific access path to described [artifacts](#artifact). +### OCM Coordinates + +Hierarchically organized identifiers for the versions of OCM components (called `Component Identity`) and contained artifacts (called `Artifact Identity`). + ### Operations See [repository operations](#repops), [access methods](#accmeth), and [access method operations](#accmethops). From 15cd1a4f010a7f7cf22f6df589650ccd71328849 Mon Sep 17 00:00:00 2001 From: Nikolay Boshnakov Date: Thu, 23 May 2024 12:22:38 +0300 Subject: [PATCH 3/5] Resolved comment --- doc/glossary.md | 1 + 1 file changed, 1 insertion(+) diff --git a/doc/glossary.md b/doc/glossary.md index da07649..4afe09c 100644 --- a/doc/glossary.md +++ b/doc/glossary.md @@ -85,6 +85,7 @@ The globally unique identity of a [component version](#compvers). ### [Component Version Reference](02-processing/01-references.md#referencing) A reference to a [component versions](#compvers) in a component version to describe an aggregation relationship. +A reference to one or multiple other [component versions](#compvers) in a component version to describe an aggregation relationship. ## D From df1adecd4eeba1ad03544ca7921024f3bea67756 Mon Sep 17 00:00:00 2001 From: Nikolay Boshnakov Date: Thu, 23 May 2024 12:44:12 +0300 Subject: [PATCH 4/5] Removed line --- doc/glossary.md | 1 - 1 file changed, 1 deletion(-) diff --git a/doc/glossary.md b/doc/glossary.md index 4afe09c..d5269b1 100644 --- a/doc/glossary.md +++ b/doc/glossary.md @@ -84,7 +84,6 @@ The globally unique identity of a [component version](#compvers). ### [Component Version Reference](02-processing/01-references.md#referencing) -A reference to a [component versions](#compvers) in a component version to describe an aggregation relationship. A reference to one or multiple other [component versions](#compvers) in a component version to describe an aggregation relationship. ## D From 35ae079ab30bbdc729320c6cc126aceba96511f7 Mon Sep 17 00:00:00 2001 From: Nikolay Boshnakov Date: Mon, 27 May 2024 17:55:36 +0300 Subject: [PATCH 5/5] Resolved comments --- doc/glossary.md | 34 +++++++++++++++++++++------------- 1 file changed, 21 insertions(+), 13 deletions(-) diff --git a/doc/glossary.md b/doc/glossary.md index d5269b1..8f51372 100644 --- a/doc/glossary.md +++ b/doc/glossary.md @@ -6,7 +6,7 @@ ### [Access Method](01-model/07-extensions.md#access-methods) -Defines how to access the content of an [artifact](#artifact). +Defines how to access the [content](#content) of an [artifact](#artifact). ### [Access Method Operations](01-model/07-extensions.md#access-method-operations) @@ -14,19 +14,19 @@ The operations an implementation of an [access method](#accmeth) has to support. ### [Access Method Type](04-extensions/02-access-types/README.md) -The type of an [access specification](#accspec) determining the formal procedure to use to access the blob content of an [artifact](#artifact). +The type of an [access specification](#accspec) determining the formal procedure to use to access the [content](#content) of an [artifact](#artifact). ### [Access Specification](01-model/07-extensions.md#access-specification) -The specification of the technical access path to the physical blob content of an [artifact](#artifact). +Technical access path to the [content](#content) of an [artifact](#artifact). ### [Aggregation](02-processing/01-references.md) -The ability of the Open Component Model to compose component versions based on other component versions. +Grouping multiple OCM component versions by referencing from a root component version. ### [Artifact](01-model/02-elements-toplevel.md#artifacts-resources-and-sources) -Blob content described by a [component version](#component-version). +[Content](#content) described by a [component version](#component-version). ### [Artifact Digest](02-processing/03-signing-process.md#determing-the-artifact-digests) @@ -34,7 +34,7 @@ The (logical) digest of an [artifact](#artifact). ### [Artifact Normalization](02-processing/06-artifact-normalization.md) -The transformation of a technical blob content of an [artifact](#artifact) depending on its type into a serialization-agnostic digest. +The transformation of a technical [content](#content) of an [artifact](#artifact) depending on its type into a serialization-agnostic digest. ### [Artifact Reference](02-processing/01-references.md#referencing) @@ -42,7 +42,7 @@ A relative or absolute reference to an [artifact](#artifact) described by a [com ### [Artifact Type](01-model/02-elements-toplevel.md#artifact-types) -The formal type of an [artifact](#artifact) described by a [component version](#compvers). The type implies the logical interpretation of the artifact blob. +The formal type of an [artifact](#artifact) described by a [component version](#compvers). The type implies the logical interpretation of the artifact. ## C @@ -60,19 +60,23 @@ The formal description of a [component version](#compvers). ### [Component Descriptor Normalization](02-processing/05-component-descriptor-normalization.md) -The mapping of the elements of a [component descriptor](#compdesc) into an immutable format containing only signature relevant information used to calculate a digest. +The mapping of the elements of a [component descriptor](#compdesc) into stable format containing only signature relevant information used to calculate a digest. ### [Component Identity](01-model/02-elements-toplevel.md#component-identity) The globally unique identity of a [component](#component). +### Component Name + +Identifies a component. + ### [Component Repository](01-model/01-model.md#component-repositories) An entity able to store and retrieve [component versions](#compvers). See also [Normalization](#norm) ### [Component Version](01-model/01-model.md#components-and-component-versions) -A dedicated version of a [component](#component) described by the Open Component Model described by a [component descriptor](#compdesc) and retrievable from a [component repository](#comprep). +A dedicated version of a [component](#component) described by a [component descriptor](#compdesc) and retrievable from a [component repository](#comprep). If used with a [component name](#compname), identifies a specific component version. ### [Component Version Digest](02-processing/05-component-descriptor-normalization.md#component-descriptor-normalization) @@ -86,6 +90,10 @@ The globally unique identity of a [component version](#compvers). A reference to one or multiple other [component versions](#compvers) in a component version to describe an aggregation relationship. +### Content + +Machine-readable data, typically organized into octets. + ## D ### Digest @@ -142,7 +150,7 @@ An [access method](#accmeth) used to access blobs stored along with a component ### [Localization](./05-guidelines/02-contract.md#example-helm-deployment) -The process of adapting content delivered as [artifacts](#artifact) in a [component versions](#compvers) to a local repository landscape in a target environment. +The process of adapting [content](#content) delivered as [artifacts](#artifact) in a [component versions](#compvers) to a local repository landscape in a target environment. ## M @@ -152,7 +160,7 @@ The mapping of the [elements](01-model/02-elements-toplevel.md) of the Open Comp ### [Model-Tool Contract](./05-guidelines/02-contract.md) -The agreement between the Open Component Model and tools working with content provided by [component versions](#compvers), which regulates the cooperation between both. +The agreement between the Open Component Model and tools working with [content](#content) provided by [component versions](#compvers), which regulates the cooperation between both. ## N @@ -230,13 +238,13 @@ A format definition for the specification of attributes for dedicated variants o ### [s3](./04-extensions/02-access-types/s3.md) -An [access method](#accmeth) used to access blobs in an S3 repository, a [mapping](#mapping) to store content in an S3 repository +An [access method](#accmeth) used to access blobs in an S3 repository, a [mapping](#mapping) to store [content](#content) in an S3 repository ## T ### [Transport](05-guidelines/01-transport.md) -The operation on [component versions](#compvers) transferring content from one OCM repository into another one. +The operation on [component versions](#compvers) transferring [content](#content) from one OCM repository into another one. ### Type