From 003523a223f33c160986fc8e28c10755eea24caf Mon Sep 17 00:00:00 2001
From: Nick Coghlan <ncoghlan@gmail.com>
Date: Nov 06 2017 14:16:21 +0000
Subject: Issue #76: Expand on module maintenance guide


Initial introduction to modules in the section about
building them.

This establishes some of the terms maintainers will
need to know in order to choose appropriate values,
and to understand the significance of existing values.

---

diff --git a/source/development/building-modules.rst b/source/development/building-modules.rst
index ca47454..377d2d6 100644
--- a/source/development/building-modules.rst
+++ b/source/development/building-modules.rst
@@ -3,13 +3,53 @@ Building Modules
 
 .. rubric:: TOC
 
+Historically, all packages in Fedora have followed the same branching structure
+in dist-git: each package had a separate branch for every numbered Fedora
+release, and if you wanted to update a package across all supported releases,
+you needed to submit the same change for each release branch.
+
+The module definition mechanism introduced in Fedora 27 allows this to be
+separated such that:
+
+* package definitions in the
+  [RPMs section](https://src.fedoraproject.org/projects/rpms/%2A)
+  of dist-git can use branches that reflect *upstream* API and ABI compatibility
+  assurances (for example, using Python's X.Y release numbers for `python3`
+  package branches)
+* module definitions in the
+  [modules section](https://src.fedoraproject.org/projects/modules/%2A)
+  of dist-git can use branches that reflect a chosen stability period, whether
+  that's tracking a particular upstream release series, a set of arbitrary
+  calendar dates, a particular Fedora release, or even just the main line of
+  upstream development.
+* the system profile for a given release then nominates the default streams
+  for each module known to the system. For example, the system profile for
+  the F27 modular server release can be found in the f27 branch of the
+  [fedora-modular-server repo](https://src.fedoraproject.org/rpms/fedora-modular-release/blob/f27/f/fedora-modular.defaults)
+  in dist-git.
+
+On the Fedora usage side, the advantage to end users of the module system, is
+that while the system profile specifies a *default* stream, it typically
+doesn't keep end users from *changing* that stream (modules with streams that
+specifically track particular Fedora releases may be an exception).
+
+For example, Fedora 27 will select `8` as the default stream for the Node.js
+module. If you run `dnf install nodejs` in F27 Modular Server, it will
+implicitly give you a `nodejs-8` RPM. However, unlike a traditional
+Fedora release, you're also able to explicitly opt-in to downgrading to the
+Node.js 6 LTS release by running the command `dnf install nodejs:6`.
+
+Note: the wrong default Node.js stream is currently selected in the F27 Modular
+Server beta (see [BZ#1509980](https://bugzilla.redhat.com/show_bug.cgi?id=1509980)).
+That problem will be corrected prior to the final release.
+
 .. toctree::
     :maxdepth: 1
 
 
     building-modules/naming-policy
     building-modules/developing
-    building-modules/building-local
     building-modules/adding-modules-to-fedora
     building-modules/building-infra
     building-modules/testing
+    building-modules/building-local