With modules, we can select any branch of any dist-git component to be included in a module. There is no requirement that the branches be named for a particular release of Fedora. As a result, it starts to make sense for components to be branched based on the upstream version of the content. However, we would like to retain consistency in Fedora which leads us to this policy. Specifically:
In order to coexist with the traditional distribution, most branches will continue to require names that align with a Fedora release and so the guidance below should be considered only for components that are not in the traditional release (e.g. fedora-modular-release).
A branch name should follow the versioning of the upstream component. This will allow us to reuse the same source branches across multiple Fedora platform binary streams (aka, Fedora versions), reducing maintainer workload.
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, 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.
If the SRPM is specifically Fedora content (e.g. fedora-logos), then it should follow the Fedora release cadence and be named for the X-branch. In other words, fedora-logos would have a f27 branch, f28 branch, etc.
We need a convention for branch naming (which results in stream names) that is logical and consistent across the project without locking everything to a Fedora version.
If your module is tightly coupled (either technically or in lifecycle) to a particular platform module stream (e.g. platform:f27) your module branch should be named the same. For example, for the networking-base module, you should create a stream called “f27.”
If your module is loosely coupled from the platform module stream, then the name of your branch follows 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, 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” branch is the preferred name.
If your module is a “collection of items” with no primary piece of software (e.g. system-tools, hardware-support), 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.
Please keep in mind that there is other metadata that can be used to find a very specific release in the unusual case where it is needed. As a result, there is no need to recreate it here. We also have metadata that indicates the EOL of the module which obviates the need to encode that here either.
Any module can address any version of an SRPM. In other words, a module can choose to consume any branch of the rpms they are interested in. However, one must be careful to monitor the EOL of the branch(es) they are choosing and be sure it aligns with the module. We expect to be alleviating this problem in two ways soon. One, monitor for EOL “violations” (shorter EOL than the module EOL). Two, allow for a module to use something akin to “f27+” allowing for the module to automatically update and be tested against new versions of subcomponents.
