#23 add naming guidelines
Merged 8 months ago by asamalik. Opened 8 months ago by asamalik.

file modified
+1

@@ -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]

@@ -0,0 +1,63 @@

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

+ 

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

+ 

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

+ 

+ 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

+ 

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

+ 

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

+ 

+ === 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:

+ 

+ * "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

+ 

+ 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

+ 

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

+ 

+ 

+ 

no initial comment
  • Don't use stable naming anywhere. It is really bad idea. stable == dead.
  • Probably use nodejs with streams 6 + 8 is better than having 9.6 + 10. It is confusing for ppl.
  • Get rid out of golang-ecosystem in examples. It is leftover from modularity v1.
  • Use master instead of experimental.
  • Add hint about default profile.
  • Rephrase section about package naming. I would probably even remove it.

Thanks for the feedback! For the record, we've also discussed this on #fedora-modularity, so I'm also using that feedback in the change.

Don't use stable naming anywhere. It is really bad idea. stable == dead.

There is a case when it makes sense, but explanation didn't make it clear. I've fixed that explanation.

Probably use nodejs with streams 6 + 8 is better than having 9.6 + 10. It is confusing for ppl.

I agree. In the end I've included both, nodejs 6 and 8, and postgresql 9.6 and 10 with an extra note about the streams, because I liked the "client" and "server" profile example I couldn't use with nodejs.

Get rid out of golang-ecosystem in examples. It is leftover from modularity v1.

It's a real example, though. Could such pattern be used for stream expansion over multiple versions of runtime? Either with a build for each, or just a single build + runtime compatibility with all?

Use master instead of experimental.

Developers usually know what master is, but what about users? I think something like "experimental" better communicates that message, but that word could be too long or sending the wrong message in some cases.

So in the end, I've used "latest" and extended the comment to better explain the cases when this should be used. Also, there are already some modules using "latest" for this exact purpose.

Add hint about default profile.

+1

Rephrase section about package naming. I would probably even remove it.

What I wanted to say here is that Modularity introduces no changes in this regard. Rephrased.

1 new commit added

  • apply PR feedback
8 months ago

I might make example 2 include a hypothetical example like "Includes postgresql and the compatible version of python-pgsql". This would serve to reinforce that modules can be more than one package but should be named after their primary purpose, in this case "postgresql".

We should also note that compatibility on non-technical fronts is also important. 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.

You use XXXX.MINOR for the CalVer but then immediately refer to "version" where you (I think) mean "MINOR".

Additionally, what is the "serial number"? You reference it but don't define it.

I'd rephrase this as "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."

Do not use "i.e." here. You probably meant "e.g." (I.e. means "this and only this". e.g. means "This is one of many possible examples). Use of "etc." with "e.g." is redundant.

You're making some very good points, @sgallagh. Let me do everything you said.

1 new commit added

  • apply additional PR feedback
8 months ago

Looks good to me now. Go ahead and merge it.

Awesome, thanks all for the review!

Pull-Request has been merged by asamalik

8 months ago