Cleaned up Glossary and added "OCM Coordinates" term

[n-boshnakov]

What this PR does / why we need it:
This PR:

• adds the term "OCM Coordinates" to the Glossary
• cleans up existing content in the Glossary

Which issue(s) this PR fixes:
Fixes #

Special notes for your reviewer:
A link to the topic describing the term "OCM Coordinates" that was sent in the original email would be appreciated, as it could be linked and provide better context for the term.

Release note:

Added "OCM Coordinates" term to the Glossary

[morri-son]

Check the linked content. Maybe we copy the text from the mail to here. The Component name should be added as own entry in the glossar, too, and also linked, same as the component version.

The Component identity consists of

• Component Name: identifies component. Should follow conventions similar to DNS (start with URL-prefix controlled by Component-Owner)

• Component Version: if used with a component name, identifies a specific Component Version. Must adhere to "relaxed Semver" (major, minor (+optional patchlevel) - optional v-prefix).

[ccwienk]

considering the wording, I think immutable is not quite adequate. I think it would be better to call this form stable (iff [sic!] no content changes occur, the normalised form will remain unchanged).

[morri-son]

Since the OCM coordinates will become a central term, I guess we can take over the full text of the mail to the glossary, although it contains many other definitions. This makes it easier to consume all information at one place without having the need to follow the links. @n-boshnakov what do you think?

OCM Coordinates are used to reference OCM Component Versions and artefacts within OCM Component Versions. Coordinates referring to an OCM Component Version are also called Component Identity, whereas relative coordinates referring to an artefact are called Artefact Identity. Component Identities are globally unique and may be used to refer to full Component Versions. Artefact Identities are always relative to an OCM Component Version and may only be used in conjunction with a Component Identity.

In detail:

Component Identity

• Component Name: identifies component. Should follow conventions similar to DNS (start with URL-prefix controlled by Component-Owner)
• Component Version: if used with a component name, identifies a specific Component Version. Must adhere to "relaxed Semver" (major, minor (+optional patchlevel) - optional v-prefix).

Artefact Identity
Within a Component Version, all artefacts must have a unique identity. The identity always includes:

• Kind (artefacts are either sources or resources)
• Name: A name (typically used to express the intended purpose)

Artefacts may also have additional attributes (called extraIdentity) that contribute to their identities. extraIdentity attributes are string-to-string maps.

Examples

Assuming there is a component named example.org/my-component, with two versions 1.2.3 and 1.3.0, declaring a resource named my-resource, then the following OCM Coordinates can be used to reference different things:

• example.org/my-component: all versions of the component (1.2.3 + 1.3.0)
• example.org/my-component:1.2.3: version 1.2.3 of the component
• example.org/my-component:1.2.3:resource/my-resource: my-resource as declared by the component version

[n-boshnakov]

The glossary should be a place for short definitions only. What we could do is take the content of the email and place it in a separate topic, then link to it from the term.

As the content of the email is already formatted in Markdown, this leads me to believe that it already exists somewhere as a topic, therefore we could just link to it. If that is not true, however, I could create a new topic with that content in this repository and link to it instead. I just need to know the correct folder to place the topic in.

[ccwienk]

@n-boshnakov : it is formatted in markdown mostly because I write in markdown(-ish) as a habit. the text was written ad-hoc.

[n-boshnakov]

In that case, I think it would be best if this information is placed in a repo as a topic. We can then link it to the new term being introduced for ease of access.

[ccwienk]

generally speaking, there seem to be a lot of changes to formatting (short lines being merged into longer ones). Is there a reason for doing that?

[n-boshnakov]

generally speaking, there seem to be a lot of changes to formatting (short lines being merged into longer ones). Is there a reason for doing that?

The definitions being split in different lines resulted in some cases of unnecessary capitalization. As I fixed those, I standardized the rest of the definitions (1 line instead of 2) in order to prevent this issue from occurring in the future.

Example:
The specification of the technical access path to the physical blob content of
An artifact.

[ccwienk]

@n-boshnakov : I see. markdown has its quirks. very unfortunate.