dmach/modularity

Forked from modularity
Fedora Modularity page. Please send a PR to edit the website.

Commit 606e99d Document naming policy.

2 files Authored and Committed by dmach a year ago
Document naming policy.

    
1 @@ -7,6 +7,7 @@
2       :maxdepth: 1
3   
4   
5 +     building-modules/naming-policy
6       building-modules/developing
7       building-modules/module-guidelines
8       building-modules/building-local
  1 @@ -0,0 +1,112 @@
  2 + =============
  3 + Naming Policy
  4 + =============
  5 + This document defines naming policy for modulemd metadata of final (built) modules.
  6 + This policy does **NOT** apply on sources such as modulemd yaml in dist-git.
  7 + 
  8 + The goal is to provide unique identifiers for modules
  9 + that are both human readable and also suitable for machine processing.
 10 + 
 11 + 
 12 + Fields
 13 + ------
 14 + 
 15 + * **N** - Name
 16 + * **S** - Stream
 17 + * **V** - Version
 18 + * **C** - Context
 19 + * **A** - Arch
 20 + * **P** - Profile
 21 + 
 22 + 
 23 + Separators
 24 + ----------
 25 + | Fields are separated with ':' (colon): N:S:V:C:A.
 26 + | If P is specified, it's separated from N:S:V:C:A with '/' (forward slash): N:S:V:C:A/P.
 27 + 
 28 + Examples::
 29 + 
 30 +     # N:S:V:C:A
 31 +     base-runtime:fedora-26:1:0123abcd:x86_64
 32 + 
 33 +     # N:S:V:C:A/P
 34 +     base-runtime:fedora-26:1:0123abcd:x86_64/minimal
 35 + 
 36 + 
 37 + Forms
 38 + -----
 39 + A form is a sequence of fields that fully or partially identifies a module.
 40 + 
 41 + 
 42 + Full Forms
 43 + ~~~~~~~~~~
 44 + 
 45 + N:S:V:C:A
 46 +     Unique identifier of a module.
 47 + N:S:V:C:A/P
 48 +     Unique identifier of a module profile.
 49 + 
 50 + 
 51 + Partial Forms
 52 + ~~~~~~~~~~~~~
 53 + 
 54 + Supported partial forms are: N [ : S [ :V [ :C ] ] ] [ :A ] [ /P ]
 55 + 
 56 + Namely:
 57 + 
 58 + * N
 59 + * N::A
 60 + * N:S
 61 + * N:S::A
 62 + * N:S:V
 63 + * N:S:V::A
 64 + * N:S:V:C
 65 + * N:S:V:C:A (identical to N:S:V:C::A)
 66 + * and all combinations with /P
 67 + 
 68 + Missing fields **SHOULD** be populated with recommended defaults:
 69 + 
 70 + Stream
 71 +     defaults to the enabled or system default stream for the module in this particular order
 72 + Version
 73 +     defaults to the latest available version in the module stream
 74 + Context
 75 +     defaults to a value matching with already installed modules or modules involved in the transaction (not yet installed)
 76 + Arch
 77 +     defaults to the system arch (e.g. DNF's $basearch)
 78 + Profile
 79 +     defaults to the system default or 'default' profile
 80 + 
 81 + 
 82 + Allowed Characters
 83 + ------------------
 84 + **N** - Name
 85 +     a-z A-Z 0-9 . - _ +
 86 + **S** - Stream
 87 +     a-z A-Z 0-9 . - _ +
 88 + **V** - Version
 89 +     0-9
 90 + **C** - Context
 91 +     0-9 a-f
 92 + **A** - Arch
 93 +     a-z A-Z 0-9 . - _ +
 94 + **P** - Profile
 95 +     a-z A-Z 0-9 . - _ +
 96 + 
 97 + All fields **MUST** start and end with an alphanumeric character:
 98 + a-z A-Z 0-9
 99 + 
100 + 
101 + Forbidden Characters
102 + --------------------
103 + This paragraph serves as a design decision for future changes.
104 + 
105 + Following characters **MUST NOT** be part of any field:
106 + 
107 + * ':' (colon) - separator
108 + * '/' (forward slash) - profile separator
109 + * '\\\\' (backslash) - comon control character
110 + * '*' (asterisk) - common wildcard
111 + * '?' (question mark) - common wildcard
112 + * '@' (at) - grpspec in YUM and DNF
113 + * ' ' (space) - common separator