From 2b5ee16197307afa3e1ad192a1222c4d3291489b Mon Sep 17 00:00:00 2001 From: Adam Samalik Date: Aug 13 2018 13:38:53 +0000 Subject: [PATCH 1/3] add naming guidelines --- diff --git a/modules/ROOT/nav.adoc b/modules/ROOT/nav.adoc index f2ebc75..6f0b906 100644 --- a/modules/ROOT/nav.adoc +++ b/modules/ROOT/nav.adoc @@ -10,6 +10,7 @@ ** xref:making-modules/building-modules-locally.adoc[Building Modules Locally] ** xref:making-modules/defining-modules.adoc[Defining Modules in modulemd] ** xref:making-modules/managing-defaults.adoc[Managing Defaults] +** xref:making-modules/naming-guidelines.adoc[Naming Guidelines] * xref:using-modules.adoc[Using Modules] * xref:community.adoc[Community] ** xref:community/teams.adoc[Teams and Working Groups] diff --git a/modules/ROOT/pages/making-modules/naming-guidelines.adoc b/modules/ROOT/pages/making-modules/naming-guidelines.adoc new file mode 100644 index 0000000..e6f8079 --- /dev/null +++ b/modules/ROOT/pages/making-modules/naming-guidelines.adoc @@ -0,0 +1,55 @@ += Modularity Naming Guidelines + +Each module has a **name**, and one or more **streams** that usually represent a major version of the application, language stack, or other software in the module. To simplify their installation, modules can define **profiles** representing a specific use case. Modules are built out of SRPM packages that have a name and one or more branches. + +**Example:** A PostgreSQL module could be named as "postgresql", its two streams could be "9.6" and "10", 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. + +== 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". + +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. + +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. + +A module stream name maps to its branch name in DistGit. + +=== Unified stream names + +In some cases, there are many suitable alternatives for for one meaning i.e. "stable" or "latest". We believe that choosing one that would be consistently used across all modules that need such profile would lead to a better user experience. The ones identified are listed below: + +* "stable" for projects without a traditional versioning scheme +* "experimental" for projects without a traditional versioning scheme + +== Module profile name and description + +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. + +Descriptions should be a short summary describing the profile. Including it is important especially for potential translations, as profile names won't be translated. + +=== Unified profile names + +In some cases, there are many suitable alternatives for for one meaning i.e. "dev", "devel", and "development". We believe that choosing one that would be consistently used across all modules that need such profile would lead to a better user experience. The ones identified are listed below: + +* "devel" for development-related profiles +* "client" only the client component of a piece of software (e.g. database client) +* "server" only the server component of a piece of software (e.g. database server) + +== Package name +Packages included in modules should use the same naming conventions as traditionally-built packages. No changes at this level. + +== Package branch name + +Packages included in modules should be branched in a similar manner as modules. So instead of having one branch for release (such as "f27", "f28, etc.), using upstream major versions as branches is recommended. Please read the Module stream name section above for guidance. + +The exact branching should be chosen with consideration given to the upstream community’s adherence to API/ABI stability on the versions of their software. In other words, in the context of X.Y.Z style naming, 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. + +For "rolling release" projects that don’t change their API/ABI (e.g. Python’s timezone database, `pytz`) a single "stable" branch is appropriate. + + + From 7a629dde495e3684dc42418107be707519debeb8 Mon Sep 17 00:00:00 2001 From: Adam Samalik Date: Aug 14 2018 06:39:47 +0000 Subject: [PATCH 2/3] apply PR feedback --- diff --git a/modules/ROOT/pages/making-modules/naming-guidelines.adoc b/modules/ROOT/pages/making-modules/naming-guidelines.adoc index e6f8079..8ecd5a2 100644 --- a/modules/ROOT/pages/making-modules/naming-guidelines.adoc +++ b/modules/ROOT/pages/making-modules/naming-guidelines.adoc @@ -2,7 +2,9 @@ Each module has a **name**, and one or more **streams** that usually represent a major version of the application, language stack, or other software in the module. To simplify their installation, modules can define **profiles** representing a specific use case. Modules are built out of SRPM packages that have a name and one or more branches. -**Example:** A PostgreSQL module could be named as "postgresql", its two streams could be "9.6" and "10", 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 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. == 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". @@ -19,10 +21,10 @@ A module stream name maps to its branch name in DistGit. === Unified stream names -In some cases, there are many suitable alternatives for for one meaning i.e. "stable" or "latest". We believe that choosing one that would be consistently used across all modules that need such profile would lead to a better user experience. The ones identified are listed below: +In some cases, there are many suitable alternatives a single meaning, i.e. "master", "experimental", or "devel". We believe that choosing one that would be consistently used across all modules that need such stream would lead to a better user experience. The ones identified are listed below: -* "stable" for projects without a traditional versioning scheme -* "experimental" for projects without a traditional versioning scheme +* "stable" for special cases when the module doesn’t really conform to a versioning scheme (e.g. Python’s timezone database, `pytz`). +* "latest" for projects without a traditional versioning scheme, or for experimental or development branches that have not been released under a specific version. A Git analogy would the "master" branch. == Module profile name and description @@ -36,12 +38,14 @@ Descriptions should be a short summary describing the profile. Including it is i In some cases, there are many suitable alternatives for for one meaning i.e. "dev", "devel", and "development". We believe that choosing one that would be consistently used across all modules that need such profile would lead to a better user experience. The ones identified are listed below: +* "default" a default profile for a "standard" instalation, should the module have something like this * "devel" for development-related profiles * "client" only the client component of a piece of software (e.g. database client) * "server" only the server component of a piece of software (e.g. database server) == Package name -Packages included in modules should use the same naming conventions as traditionally-built packages. No changes at this level. + +No changes for package names with Modularity. Please refer to the official https://fedoraproject.org/wiki/Packaging:Naming?rd=Packaging:NamingGuidelines[Guidelines for Naming Fedora Packages]. == Package branch name From 9e610664d9bbcd81803ea97b21c1bbd5e5787563 Mon Sep 17 00:00:00 2001 From: Adam Samalik Date: Aug 14 2018 12:36:37 +0000 Subject: [PATCH 3/3] 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.