From c282561ed63fae5e1aeba482beb4ba814eba6dfb Mon Sep 17 00:00:00 2001 From: langdon Date: Nov 16 2017 21:01:35 +0000 Subject: [PATCH 1/3] adding a few things to gitignore --- diff --git a/.gitignore b/.gitignore index d76b74e..630b5a5 100644 --- a/.gitignore +++ b/.gitignore @@ -1,2 +1,4 @@ build .DS_Store +_build +.vscode From 9e8a5798c7ad27ec34779e20e122f39cc316a3a1 Mon Sep 17 00:00:00 2001 From: langdon Date: Nov 16 2017 21:02:47 +0000 Subject: [PATCH 2/3] adding naming guidelines to the website, probably should be moved to the wiki guidelines after a bit of a comment period --- diff --git a/source/development/building-modules.rst b/source/development/building-modules.rst index a8176cc..0a88df7 100644 --- a/source/development/building-modules.rst +++ b/source/development/building-modules.rst @@ -61,4 +61,6 @@ Node.js 6 LTS release by running the command ``dnf install nodejs:6``. building-modules/installation-dependency-issues building-modules/building-local building-modules/naming-policy + building-modules/branch-naming + diff --git a/source/development/building-modules/branch-naming.rst b/source/development/building-modules/branch-naming.rst new file mode 100644 index 0000000..5193dc5 --- /dev/null +++ b/source/development/building-modules/branch-naming.rst @@ -0,0 +1,105 @@ +============= +Branch Naming in dist-git Guidelines (proposed) +============= + +RPM branch naming +----------------- + +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 27 branch, 28 branch, etc. + +Module branch naming +-------------------- + +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. + +Module branch consumption +------------------------- + +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. + +.. figure:: modular-branching-and-building.png + :alt: modular-branching-and-building.png \ No newline at end of file From 4f1536852f2da0d23d0fc711c7f16e34f9874279 Mon Sep 17 00:00:00 2001 From: Langdon White Date: Nov 30 2017 15:42:47 +0000 Subject: [PATCH 3/3] Update source/development/building-modules/branch-naming.rst minor edit for clarification --- diff --git a/source/development/building-modules/branch-naming.rst b/source/development/building-modules/branch-naming.rst index 5193dc5..05ff07e 100644 --- a/source/development/building-modules/branch-naming.rst +++ b/source/development/building-modules/branch-naming.rst @@ -39,7 +39,7 @@ 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 27 branch, 28 branch, etc. +In other words, fedora-logos would have a f27 branch, f28 branch, etc. Module branch naming --------------------