From de56fac49be70d606be2b2431303d32ecf35c61e Mon Sep 17 00:00:00 2001 From: Martin Curlej Date: May 05 2020 07:19:32 +0000 Subject: Consolidation of NSVCA page The information about the NSVCA was fragmented through several pages. There where not enough information to justify 3 pages. Issue: modularity#174 Signed-off-by: Martin Curlej --- diff --git a/modules/ROOT/nav.adoc b/modules/ROOT/nav.adoc index dc7bd6e..2daee0a 100644 --- a/modules/ROOT/nav.adoc +++ b/modules/ROOT/nav.adoc @@ -28,9 +28,7 @@ * **Advanced** * xref:hosting-modules.adoc[Creating Modular Repositories] * xref:using-other-build-systems.adoc[Using Other Build Systems] -* xref:architecture/building/name-and-id.adoc[NSVCA (Module ID)] -** xref:architecture/module-version-prefix.adoc[Version Prefix] -** xref:architecture/consuming/naming-policy.adoc[NSVCA Definition] +* xref:architecture/nsvca.adoc[NSVCA vs NEVRA] * **Other** * xref:references.adoc[References] diff --git a/modules/ROOT/pages/architecture/building/name-and-id.adoc b/modules/ROOT/pages/architecture/building/name-and-id.adoc deleted file mode 100644 index bb74f85..0000000 --- a/modules/ROOT/pages/architecture/building/name-and-id.adoc +++ /dev/null @@ -1,52 +0,0 @@ -= Naming and identifying modules in Fedora - -Modules are uniquely identified by NSVCA which stands for _name_, _stream_, _version_, _context_, and _architecture_. This page describes both the source-level ID (NSV) and the binary-level ID (NSVCA). - -== Source-level ID (NSV) - -At the source level, modules are only identified by the first three: _name_, _stream_, and _version_. Name is defined as a name of the module's repository in DistGit, stream is a name of the branch in DistGit, and version is the timestamp of a commit. - -=== Name - -Name of the module corresponds to the name of the application or the language stack it represents. - -An example of a name could be _postgresql_ for a PostgreSQL database module, or _nodejs_ for a Node.js runtime. - -=== Stream - -Streams are variants of a module with a certain promise. - -In most cases, streams promise *backwards compatibility* with a major version of the application or the language stack they provide. For example, let's say the Node.js runtime is supported in two major versions: 6 and 8. In this case, the module _nodejs_ would have two streams: _6_ and _8_. - -However, streams can also promise different things such as *stability*. A good example of this is the _calc_ package in Fedora which is maintained in two upstream branches: _stable_ for the latest stable release and _unstable_ for the latest development version. Using modularity, this package could be built as a _calc_ module in two different streams: _stable_ and _unstable_. - -In addition to the version promise, streams are also a way for packagers to communicate the *level of maintenance*. Does the maintainer plan to apply every minor patch? Will they apply security fixes quickly? Or is the module updated only twice a year? This can also be part of the promise. - -Other different example could be a stream that provides the software compiled using some experimental flags increasing the performance. - -Anyway, you get the idea. Streams are very flexible and powerful tool. Use them wisely. - -=== Version - -Versions are just updates of a given stream. Technically, version is a number generated by the build system. Higher number always wins. - -== Binary-level ID (NSVCA) - -Building a module from one source can result in multiple different binaries. Different binaries are typically produced for different architectures (i.e. _x86_64_, _armv7hl_, etc.) and different Fedora releases (i.e. Fedora 28, Fedora 29, EPEL 7, etc.). - -Module binaries use the full NSVCA — so in addition to the _name_, _stream_, and _version_ fields described above, there are two more for binaries: _architecture_ and _context_. - -=== Architecture - -https://fedoraproject.org/wiki/Architectures[ Fedora is built for many different architectures]. The architecture field simply distinguishes architecture-specific binaries from each other. - -The value is typically the same as with RPM packages, i.e. _x86_64_, _armv7hl_, etc. - -=== Context - -Context is used to distinguish binaries built for different Fedora releases. Thanks to https://fedoraproject.org/wiki/Infrastructure/Factory2/Focus/StreamExpansion[stream expansion], modules can also be built against multiple streams of other modules, i.e. different versions of a language runtime etc. - -The value is generated by the build system and is usually hidden from the user as it doesn't have any informational value by itself — it is a hash. However, the client tooling consuming this value can present it in a useful way. - -One way of representing the context could be listing the Fedora releases for which a certain module has been built. - diff --git a/modules/ROOT/pages/architecture/consuming/naming-policy.adoc b/modules/ROOT/pages/architecture/consuming/naming-policy.adoc deleted file mode 100644 index 8e49c27..0000000 --- a/modules/ROOT/pages/architecture/consuming/naming-policy.adoc +++ /dev/null @@ -1,108 +0,0 @@ -= NSVCA Definition - -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 diff --git a/modules/ROOT/pages/architecture/module-version-prefix.adoc b/modules/ROOT/pages/architecture/module-version-prefix.adoc deleted file mode 100644 index d18067d..0000000 --- a/modules/ROOT/pages/architecture/module-version-prefix.adoc +++ /dev/null @@ -1,22 +0,0 @@ -= Module Version Prefix - -Modules built with Module Build Service (MBS) v2.8.1 or newer will contain a -version prefix. This prefix is derived by the stream version of the Platform -module that the module build buildrequires. For instance, if the Platfom module -has a stream of `f29`, then the stream version would be `29`. This makes it so -that a module with a version of `20181109101859` would become -`2920181109101859`. This ensures that modules built with later versions of -Fedora always have higher versions, and thefore, have a clear upgrade path. - -The reason this is needed is that a module's version is dynamically derived -from the commit timestamp of the modulemd that was used for the module build. -This becomes an issue in the following scenario. If you build a module for -Fedora 28, then build a module of the same stream for Fedora 29, then when -upgrading to Fedora 29 will work just fine because the module build for Fedora -29 was built later, so therefore has a higher version. If the module build for -Fedora 28 needs to be rebuilt however, then the version will be higher than the -Fedora 29 build since the modulemd will have a newer commit. This will mean that -a user with the Fedora 28 module version installed, will encounter issues when -upgrading to Fedora 29 since the user will already have a module with a higher -version installed than what is provided by Fedora 29. Prefixing the module -version with the buildrequired Platform stream version solves the issue. diff --git a/modules/ROOT/pages/architecture/nsvca.adoc b/modules/ROOT/pages/architecture/nsvca.adoc new file mode 100644 index 0000000..2744c61 --- /dev/null +++ b/modules/ROOT/pages/architecture/nsvca.adoc @@ -0,0 +1,166 @@ + += NSVCA vs NEVRA + +1. **<>** +2. **<>** +3. **<>** +4. **<>** + +== Naming and identifying modules in Fedora + +With the introduction of Modularity to the packager ecosystem it also introduced several challenges. First was that the NEVRA (name-epoch-version-release-architecture) package naming convention used in Fedora was insufficient. Modules are uniquely identified by the NSVCA naming convention, which stands for _name_, _stream_, _version_, _context_, and _architecture_. This page describes both the source-level ID (NSV) and the binary-level ID (NSVCA). + +== Source-level module ID (NSV) + +At the source level, modules are only identified by the first three: _name_, _stream_, and _version_. Name is defined as a name of the module’s repository in https://src.fedoraproject.org/[DistGit], stream is a name of the branch in https://src.fedoraproject.org/[DistGit], and version is the timestamp of a commit. + +=== Name + +Name of the module corresponds to the name of the application or the language stack it represents. +An example of a name could be postgresql for a PostgreSQL database module, or nodejs for a Node.js runtime. + +=== Stream + +Streams are variants of a module with a certain promise. + +In most cases, streams promise backwards compatibility with a major version of the application or the language stack they provide. For example, let’s say the Node.js runtime is supported in two major versions: 6 and 8. In this case, the module nodejs would have two streams: 6 and 8. + +However, streams can also promise different things such as stability. A good example of this is the calc package in Fedora which is maintained in two upstream branches: stable for the latest stable release and unstable for the latest development version. Using modularity, this package could be built as a calc module in two different streams: stable and unstable. + +In addition to the version promise, streams are also a way for packagers to communicate the level of maintenance. Does the maintainer plan to apply every minor patch? Will they apply security fixes quickly? Or is the module updated only twice a year? This can also be part of the promise. + +Another different example could be a stream that provides the software compiled using some experimental flags increasing the performance. + +Anyway, you get the idea. Streams are a very flexible and powerful tool. Use them wisely. + +=== Version + +Versions are just updates of a given stream. Technically, version is a number generated by the build system. Higher number always wins. This means that version does not identify a major/minor version of the software but the update/commit to a particular stream. + + +== Binary-level ID (NSVCA) + +Building a module from one source can result in multiple different binaries. Different binaries are typically produced for different architectures (i.e. x86_64, armv7hl, etc.) and different Fedora releases (i.e. Fedora 28, Fedora 29, EPEL 7, etc.). + +Module binaries use the full NSVCA — so in addition to the name, stream, and version fields described above, there are two more for binaries: architecture and context. + +=== Architecture + +Fedora is built for many different architectures. The architecture field simply distinguishes architecture-specific binaries from each other. The value is typically the same as with RPM packages, i.e. x86_64, armv7hl, etc. + +=== Context + +Context is used to distinguish binaries built for different Fedora releases. Thanks to stream expansion, modules can also be built against multiple streams of other modules, i.e. different versions of a language runtime etc. + +The value is generated by the build system and is usually hidden from the user as it doesn’t have any informational value by itself — it is a hash. However, the client tooling consuming this value can present it in a useful way. + +One way of representing the context could be listing the Fedora releases for which a certain module has been built. + +== NSVCA Definition + +This 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 diff --git a/modules/ROOT/pages/community.adoc b/modules/ROOT/pages/community.adoc index d88e0ed..7aa24c2 100644 --- a/modules/ROOT/pages/community.adoc +++ b/modules/ROOT/pages/community.adoc @@ -3,7 +3,7 @@ This page lists the communication channels of members of the Modularity Working Group (Modularity WG), related projects and also how you can contribute to the project. 1. **<>** -3. **<>** +2. **<>** == Channels