#35 add naming policy from the old docs
Merged 6 months ago by asamalik. Opened 6 months ago by asamalik.
fedora-docs/ asamalik/modularity naming-policy  into  master

file modified
+1

@@ -3,6 +3,7 @@ 

  *** xref:architecture/building/name-and-id.adoc[Module name and ID]

  ** xref:architecture/consuming.adoc[Consuming Software]

  *** xref:architecture/consuming/dnf-behavior.adoc[DNF Behavior]

+ *** xref:architecture/consuming/naming-policy.adoc[Naming Policy]

  * xref:making-modules.adoc[Making Modules]

  ** xref:making-modules/adding-new-modules.adoc[Adding New Modules]

  ** xref:making-modules/updating-modules.adoc[Updating Existing Modules]

@@ -0,0 +1,108 @@ 

+ = Naming Policy

+ 

+ This document defines naming policy for modulemd metadata of final (built) modules.

+ This policy does **NOT** apply on sources such as modulemd yaml in dist-git.

+ 

+ The goal is to provide unique identifiers for modules

+ that are both human readable and also suitable for machine processing.

+ 

+ == Fields

+ 

+ * **N** - Name

+ * **S** - Stream

+ * **V** - Version

+ * **C** - Context

+ * **A** - Arch

+ * **P** - Profile

+ 

+ 

+ == Separators

+ 

+ Fields are separated with ':' (colon): N:S:V:C:A.

+ 

+ If P is specified, it's separated from N:S:V:C:A with '/' (forward slash): N:S:V:C:A/P.

+ 

+ === Examples

+ 

+ ----

+ # N:S:V:C:A

+ mariadb:3.6:1:0123abcd:x86_64

+ # N:S:V:C:A/P

+ mariadb:3.6:1:0123abcd:x86_64/server

+ ----

+ 

+ == Forms

+ 

+ A form is a sequence of fields that fully or partially identifies a module.

+ 

+ === Full Forms

+ 

+ N:S:V:C:A::

+     Unique identifier of a module.

+ N:S:V:C:A/P::

+     Unique identifier of a module profile.

+ 

+ 

+ === Partial Forms

+ 

+ Supported partial forms are: `N [ : S [ :V [ :C ] ] ] [ :A ] [ /P ]`

+ 

+ Namely:

+ 

+ * `N`

+ * `N::A`

+ * `N:S`

+ * `N:S::A`

+ * `N:S:V`

+ * `N:S:V::A`

+ * `N:S:V:C`

+ * `N:S:V:C:A` (identical to `N:S:V:C::A`)

+ * and all combinations with `/P`

+ 

+ Missing fields **SHOULD** be populated with recommended defaults:

+ 

+ Stream::

+     defaults to the enabled or system default stream for the module in this particular order

+ Version::

+     defaults to the latest available version in the module stream

+ Context::

+     defaults to a value matching with already installed modules or modules involved in the transaction (not yet installed)

+ Arch::

+     defaults to the system arch (e.g. DNF's $basearch)

+ Profile::

+     defaults to the system default or 'default' profile

+ 

+ 

+ === Allowed Characters

+ 

+ 

+ **N** - Name::

+     a-z A-Z 0-9 . - _ +

+ **S** - Stream::

+     a-z A-Z 0-9 . - _ +

+ **V** - Version::

+     0-9

+ **C** - Context::

+     0-9 a-f

+ **A** - Arch::

+     a-z A-Z 0-9 . - _ +

+ **P** - Profile::

+     a-z A-Z 0-9 . - _ +

+ 

+ All fields **MUST** start and end with an alphanumeric character:

+ a-z A-Z 0-9

+ 

+ 

+ === Forbidden Characters

+ 

+ This paragraph serves as a design decision for future changes.

+ 

+ Following characters **MUST NOT** be part of any field:

+ 

+ * ':' (colon) - separator

+ * '/' (forward slash) - profile separator

+ * '\\\\' (backslash) - comon control character

+ * '*' (asterisk) - common wildcard

+ * '?' (question mark) - common wildcard

+ * '@' (at) - grpspec in YUM and DNF

+ * ' ' (space) - common separator