#44 Document naming policy.
Closed 2 years ago by psabata. Opened 2 years ago by dmach.
dmach/modulemd naming-policy  into  master

file modified
+23 -1

@@ -1,8 +1,30 @@ 

  modulemd's documentation

  ========================

  

+ Contents

+ --------

+ 

+ .. toctree::

+     :maxdepth: 1

+ 

+     naming-policy

+ 

+ 

+ Python Quickstart

+ -----------------

+ 

  .. automodule:: modulemd

-    :members: none

+     :members: none

+ 

+ 

+ Python modules

+ --------------

+ 

+ .. toctree::

+     :maxdepth: 2

+ 

+     modulemd

+ 

  

  Indices and tables

  ==================

@@ -0,0 +1,92 @@ 

+ =============

+ Naming Policy

+ =============

+ This document defines naming policy for modulemd metadata.

+ 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

+ * **A** - Arch

+ * **P** - Profile

+ 

+ 

+ Forms

+ -----

+ The most common forms are NSVA and NSVAP.

+ 

+ 

+ Separators

+ ----------

+ | NSVA fields are separated with ':' (colon): N:S:V:A.

I think this is still not defined, is it?

s/defined/decided/

note that this sucks because when you do dnf install, you should be able to omit stream / arch and in this case it becomes impossible... we are back to hyphens troubles

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

+ 

+ Examples::

+ 

+     # NSVA

+     base-runtime:fedora-26:1:x86_64

+ 

+     # NSVAP

+     base-runtime:fedora-26:1:x86_64/minimal

+ 

+ 

+ Allowed Characters

I think this should go into spec.yaml rather

+ ------------------

+ **N** - Name

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

+ **S** - Stream

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

+ **V** - Version

+     0-9

+ **A** - Arch

+     a-z 0-9 - _

+ **P** - Profile

+     a-z 0-9 -

+ 

+ All fields must start and end with a number or a letter:

+ a-z A-Z 0-9

+ 

+ 

+ Forbidden Characters

+ --------------------

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

+ 

+ Following characters must never become part of any field:

+ 

+ * ':' (colon) - separator

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

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

+ * '*' (asterisk) - common wildcard

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

+ * ' ' (space) - common separator

+ 

+ 

+ File Names

+ ----------

+ Single module metadata records stored on disk must be

+ named according to their NSVA.

+ Profile must **not** be part of file name

+ as it's only an internal metadata detail,

+ which is not part of module identity::

+ 

+     $name:$stream:$version:$arch.modulemd.yaml

why does it matter how files are name? metadata is inside...

+ 

+ 

+ Example::

+ 

+     base-runtime:fedora-26:1:x86_64.modulemd.yaml

+ 

+ 

+ Repomd Repodata

+ ---------------

+ Module metadata in repomd repodata is stored as yaml multi-document.

+ It is highly recommended to sort module metadata in this multi-document

+ by NSVA to generate predictable and diffable output.

+ 

+ * Mandatory repomd.xml ID: **modules**

+ * Recommended file name: **[$hash-]modules.yaml[.$compression]**

I think this is still not defined, is it?

I think this should go into spec.yaml rather

why does it matter how files are name? metadata is inside...

Thanks for taking the time but since this is all about policies, I think this should go into the previously agreed location, i.e. the modularity docs: https://pagure.io/modularity/

note that this sucks because when you do dnf install, you should be able to omit stream / arch and in this case it becomes impossible... we are back to hyphens troubles

This seems to have stalled out. Should it be closed?

Pull-Request has been closed by psabata

2 years ago
Metadata