| |
@@ -13,22 +13,34 @@
|
| |
|
| |
== 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.
|
| |
+
|
| |
+ === 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.
|
| |
|
| |
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.
|
| |
|
| |
+ === Option 2: CalVer
|
| |
+
|
| |
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.
|
| |
+ === Option 3: Rolling and unstable streams
|
| |
|
| |
- 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.
|
| |
+ For streams that don't guarantee an API/ABI stability over time and just roll forward, we suggest packagers use one of the following stream names.
|
| |
+
|
| |
+ * "rolling" for user-focused content meant for general use
|
| |
+ * "unstable" for pre-release content or content in active development meant for preview and testing rather than general use
|
| |
+
|
| |
+ We mandate a good use of the description and/or summary field to clearly state what this particular stream represents.
|
| |
+
|
| |
+ This policy doesn't enforce changes in existing branch names, however, packagers are welcome to do so in order to bring more consistency to the distribution.
|
| |
|
| |
- === Unified stream names
|
| |
+ === Option 4: Upstream conventions
|
| |
|
| |
- 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:
|
| |
+ In case there are well-established upstream conventions, using them is also a good option.
|
| |
|
| |
- * "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.
|
| |
+ Again, especially in this case, we mandate a good use of the description and/or summary field to clearly state what this particular stream represents.
|
| |
|
| |
== Module profile name and description
|
| |
|
| |
asamalik
commented 5 years ago
based on the following decision at the Modularity Team meeting:
There will be two streams named "rolling" for the user-focused builds and "unstable" for the preview/master/pre-release things, and this will be just a suggestion to the packagers, but using whatever is established upstream is also a good option. We'll not rename nor enforce renaming of anything, we'll leave it to packagers and mandate a good use of the description summary field for this purpose. +4 0 -0