fedora-docs / modularity

Clone
Source Code
GIT

#88 Suggest to use "stream-module-version" for branches.
Opened 3 years ago by vondruch. Modified 2 years ago
fedora-docs/ vondruch/modularity prefixed-branches  into  master

Merge
file modified
+9 -7 
@@ -2,9 +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 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 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 "stream-nodejs-6", "stream-nodejs-8", and "stream-nodejs-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 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.
 

+ **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 "stream-postgresql-9.6" and "stream-postgresql-10", which would be the main package; and another one named "python-pgsql", having a single branch "stream-postgresql-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,13 @@ 
 

  

  == Module stream 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.
 

+ The module streams should be discoverable and distinguishable from the other branches. Therefore whatever stream name is chosen, it should be stored in DistGit with "stream-" prefix followed by module name. For example, having "nodejs" module with stream "10", the DistGit branch should be "stream-nodejs-10".
 

+ 

+ There are several options to choose suitable module stream names:
 

  

  === Option 1: Major version
 

  

- 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. 

+ 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 stream names should reflect that stability. For example, most communities are stable on the Y branch so the stream name should be "X.Y". (e.g. mariadb:10.2) included in the module.
 

  

  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.
 

  
@@ -65,11 +67,11 @@ 
 

  

  == 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.
 

+ 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 "stream-" prefix followed by module name and 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.
 

+ 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, if Node.js community is stable on the X branch so the branch name should be "stream-nodejs-X". 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.
 

+ For "rolling release" projects that don’t change their API/ABI (e.g. Python’s timezone database, `pytz`) a single "stable" branch with correct prefix is appropriate.

The guideline currently recommends using upstream major versions as branches. This is not acceptable, because this works just for simplest cases, such as there is module "nodejs" shipping single package "nodejs". It does not work for even slightly more complex cases when module "nodejs" includes not just "nodejs" package, but also lets say "npm" package. Having Node.js versioned brachnes in "npm" is wrong. Not mentioning that if I'll have "mynodejs" module, using both "nodejs" and "npm" and probably also other packages, the versions will be already occupied by "nodejs" module.

IOW, the modular packages must live in "stream-module-version" branches by default. This avoids conflicts and provides more understanding why "npm" package has some branches.

It would be nice if also other parts of modularity [1] were adjusted to benefit from this.

+1.

How about suggesting both? For single package modules, just a version may be okay.
I think it is hard to have a general solution for this - it is a recommendation as you say.
Maybe best practice for different ecosystems needs to be documented though?

(It is a pity that there are so few languages that have a distro.)
Edited 3 years ago by petersen

<prefix><module-name>-<module-stream>-<module-context> would be a perfect branch naming schema, because with the new modularity static contexts, NSC represents a virtual repo.

Because multi-context streams are quite rare in Fedora and as long sources are identical and only the binaries of the modules differ, using the following schema might be more reasonable: <prefix><module-name>-<module-stream>

Prefix could be stream- or module- or anything else that makes sense within the distro's branching policy.

Nobody prevents you from using that scheme in your rpms-namespace branches. If you like them, use them. The naming-policy https://docs.fedoraproject.org/en-US/modularity/policies/naming-guidelines/#_package_branch_name only recommends upstream versions. It does not mandate them.

I'm not fond of making the format mandatory because it cannot cater all use cases. For example in Perl modules, we frequently share the same RPM branch among multiple modules for build-only packages. Or we reuse non-modular branches as compensations for no default streams. One module-stream identifier cannot fit them all.

This is statistics for component refs from F36 modular repository:

# zcat /var/cache/dnf/fedora-modular-f440a08391e7b71d/repodata/9f72cb0ffbf4e7c96979c0f391c1a6b7ddeabb4c0d7288b7ffc2d4c3b794b3e3-modules.yaml.gz | grep ref: |sort | uniq -c | sort -n -r
    115         ref: f33
     56         ref: f34
     14         ref: rawhide
      5         ref: stream-postgresql-11
      3         ref: 1.22
      3         ref: stream-postgresql-12
      2         ref: 1.21
      2         ref: 1.20
      2         ref: 1
      2         ref: stream-6.0
      2         ref: latest
      1         ref: 9.2
      1         ref: 82lts
      1         ref: 81249e56
      1         ref: 8.10
      1         ref: 6.2
      1         ref: 6.1
      1         ref: 6.0
      1         ref: 4.0
      1         ref: 16
      1         ref: 14
      1         ref: 1.23
      1         ref: 1.14
      1         ref: 10.7
      1         ref: 10.6
      1         ref: 10.5
      1         ref: stream-1.20
      1         ref: stream-postgresql-14
      1         ref: stream-postgresql-10
      1         ref: stream-mainline
      1         ref: nextcloud-22
      1         ref: nextcloud-21
      1         ref: nextcloud-19
      1         ref: nextcloud-18
      1         ref: nextcloud-stable
      1         ref: mariadb-10.7
      1         ref: mariadb-10.6
      1         ref: mariadb-10.5

I'm NOT against mentioning (stream-)module-stream schema as a popular one in the guidelines, but I do not want make it obligatory.
Edited 2 years ago by ppisar

I think the proposal is using "should" and "recommended" wording, which allows exceptions IMO.

BTW, your example demonstrates quite nicely why the recommended scheme should be updated, because where it is quite nicely visible what "stream-postgresql-10" means, you might just guess what the "latest" is about. Again, this might be reasonable exception, but we should aim to make the stream branches more self describing.
Metadata
None
No Tags
Changes Summary 1
+9 -7
file changed
modules/ROOT/pages/policies/naming-guidelines.adoc
Powered by Pagure 5.13.3
Documentation • File an Issue • About • SSH Hostkey/Fingerprint
© Red Hat, Inc. and others.