From 9e610664d9bbcd81803ea97b21c1bbd5e5787563 Mon Sep 17 00:00:00 2001 From: Adam Samalik Date: Aug 14 2018 12:36:37 +0000 Subject: apply additional PR feedback --- diff --git a/modules/ROOT/pages/making-modules/naming-guidelines.adoc b/modules/ROOT/pages/making-modules/naming-guidelines.adoc index 8ecd5a2..f3f3d48 100644 --- a/modules/ROOT/pages/making-modules/naming-guidelines.adoc +++ b/modules/ROOT/pages/making-modules/naming-guidelines.adoc @@ -4,7 +4,7 @@ Each module has a **name**, and one or more **streams** that usually represent a **Example 1:** A Node.js module could be named "nodejs", with three streams "6", "8" and "10", and two profiles "default" and "devel". This module would include a single package in each stream named "nodejs", branched as "6", "8", and "10". -**Example 2:** Another one, PostgreSQL, could be named as "postgresql", its two streams could be "9.6" and "10", because that's where the upstream compatibility is, and its profiles could include "client" and "server". Both streams could be built out of a single SRPM package named "postgresql", having branches named "9.6" and "10", respectively. +**Example 2:** Another one, PostgreSQL, could be named as "postgresql", its two streams could be "9.6" and "10", because that's where the upstream compatibility is, and its profiles could include "client" and "server". Both streams could be built out of two packages. One named "postgresql", having branches "9.6" and "10", which would be the main package; and another one named "python-pgsql", having a single branch "latest", which would always bind to the right version of the database during build, and would provide Python bindings. == Module name A module usually represents an application, a language stack, or any other logical collection of packages. Module name should represent the name of the software it ships. Using lowercase, hyphen-separated names is preferable. Some examples could include "nodejs", "golang", "golang-ecosystem", or "cri-o". @@ -13,11 +13,15 @@ A module name maps to its repository name in DistGit. == Module stream name -A stream usually represents a major version of the software, and should follow the versioning of the major upstream component (e.g. mariadb:10.2) included in the module. Consideration should be given to the upstream community’s adherence to API (or even ABI) stability on the versions of their software. In other words, some communities will maintain stability on the X branch, many the Y branch, and some even the Z branch. As a result, the branch names should reflect that stability. For example, most communities are stable on the Y branch so the branch name should be "X.Y". While this rule is focusing on examples using X.Y.Z style naming, CalVer (http://calver.org/), or other versioning schemes, should be faithfully reflected using the same guidance regarding which branches to create. When the module doesn’t really conform to a versioning scheme (e.g. Python’s timezone database, `pytz`) a "stable" stream is the preferred name. +A stream usually represents a major version of the software, and should follow the versioning of the major upstream component included in the module. Consideration should be given to the upstream community’s adherence to API (or even ABI) stability on the versions of their software. In other words, some communities will maintain stability on the X branch, many the Y branch, and some even the Z branch. As a result, the branch names should reflect that stability. For example, most communities are stable on the Y branch so the branch name should be "X.Y". (e.g. mariadb:10.2) included in the module. -If your module is a "collection of items" with no primary piece of software (e.g. container-tools), the versioning scheme should use the CalVer scheme with YYYY.MINOR where the date is at time of release and the version is 0-based. In other words, if I *released* a system-tools module in November of 2017 we would expect to see 2017.0. My next release, in May of 2018, which does not break ABI/API, is also 2017.0. However, in October of 2018 we want to introduce a new stream so we name it 2018.0. The month is omitted as ideally these modules won’t be breaking API/ABI more than once a year. The serial number is included in order to handle cases where an API/ABI change needs to be reverted or otherwise modified shortly after its initial release. This serial number can also act as a replacement for months, days, or even minutes if necessary. +Compatibility on non-technical factors should be also considered. For example, a package that maintains exactly the same API but has a significant visual and UX overhaul probably belongs in a new stream. Or to put it another way, human interaction is an interface too. -A module stream name maps to its branch name in DistGit. +If your module is a "collection of items" with no primary piece of software (e.g. container-tools), the versioning scheme should use the CalVer (http://calver.org/) scheme with YYYY.MINOR where the YYYY is the year of the release and MINOR version is an integer starting at 0. In other words, if I released a system-tools module in November of 2017 we would expect to see 2017.0. My next release, in May of 2018, which does not break ABI/API, is also 2017.0. However, in October of 2018 we want to introduce a new stream so we name it 2018.0. The month is omitted as ideally these modules won’t be breaking API/ABI more than once a year. + +When the module doesn’t really conform to a versioning scheme (e.g. Python’s timezone database, `pytz`) a "stable" stream is the preferred name. + +The module stream name is assigned by creating a branch of that name in DistGit and building from it. The Module Build Service will automatically set the stream name of the resulting module to match. === Unified stream names @@ -30,7 +34,7 @@ In some cases, there are many suitable alternatives a single meaning, i.e. "mast Profiles make installation easier by giving the user some predefined package groups that represent a common installation for a specific use case. Profiles have name and a description — using both is mandatory. -Profile name should be a one word that best represent the use case. Some examples could include "client" or "server" for database modules, "default" or "devel" for language runtime modules, but also "minimal" and others. There some reserved profile names for specific purposes i.e. setting up a buildroot etc. Please see the https://github.com/fedora-modularity/libmodulemd/blob/master/spec.v2.yaml[modulemd spec] for a complete list. +Profile name should be a one word that best represent the use case. Some examples could include "client" or "server" for database modules, "default" or "devel" for language runtime modules, but also "minimal" and others. There some reserved profile names for specific purposes e.g. setting up a buildroot. Please see the https://github.com/fedora-modularity/libmodulemd/blob/master/spec.v2.yaml[modulemd spec] for a complete list. Descriptions should be a short summary describing the profile. Including it is important especially for potential translations, as profile names won't be translated.