From 0582f35d0d5f413b10c06fd93e383167b9bd93d2 Mon Sep 17 00:00:00 2001
From: Merlin Mathesius <mmathesi@redhat.com>
Date: May 23 2018 15:05:13 +0000
Subject: Add modular DNF behavior page


---

diff --git a/_topic_map.yml b/_topic_map.yml
index d0d083b..e38302e 100644
--- a/_topic_map.yml
+++ b/_topic_map.yml
@@ -34,7 +34,12 @@ Topics:
       - Name: Building Software
         File: Building_Software
       - Name: Consuming Software
-        File: Consuming_Software
+        Dir: consuming-software
+        Topics:
+        - Name: Consuming Software
+          File: Consuming_Software
+        - Name: Modular DNF Behavior
+          File: Modular_DNF_Behavior
   - Name: Making Modules
     Dir: making-modules
     Topics:
@@ -61,4 +66,3 @@ Topics:
     File: References
   - Name: FAQ
     File: FAQ
-    
\ No newline at end of file
diff --git a/en-US/architecture/Consuming_Software.adoc b/en-US/architecture/Consuming_Software.adoc
deleted file mode 100644
index b027715..0000000
--- a/en-US/architecture/Consuming_Software.adoc
+++ /dev/null
@@ -1,61 +0,0 @@
-= Consuming Software with Modularity
-
-This is a high-level overview of how users can install software with Fedora Modularity and how is it different from the traditional workflow(s).
-
-== Understanding the Delivery Channels
-
-Modular Fedora will ship with two sets of repositories:
-
-. The *traditional base repository* representing the distribution as we know it today — there are no user-visible changes in this part.
-
-. A new *modular repository*  (often referred to as the "Application Stream" or AppStream for short) including all the additional versions delivered as modules.
-
-The Modules repository will be optional for users.
-
-image::mod-doc-repositories.png[,80%,]
-
-== Consuming the traditional packages
-
-There are no changes to the traditional user experience.
-Packages from the traditional repository will be installed and updated using the same methods as before.
-Everything keeps working as it used to.
-
-== Consuming the modular packages
-
-If a user desires to use the optioanl Modular repositories in order to consume non-default versions of software, there will be some new concepts introduced in the client tooling to manage them.
-We outline these below.
-
-=== Enabling a module
-
-Enabling a module makes its packages available on the system.
-Packages delivered as part of a module always have a priority over the ones from the traditional base, regardless of their actual version.
-Packages in modules are often replacements of the ones in the traditional base.
-
-Modularity brings parallel availability, not parallel installability.
-Only one stream of a given module can be enabled on a system — so it is always clear which version gets installed.
-Installing and running multiple versions of software can be achieved by using existing technologies, such as containers.
-
-=== Installing a module
-
-To make installation easy, some modules can be also installed as a unit, without the need of enabling them first and then installing individual packages.
-Installing a module doesn’t necessarily mean installing all of its packages.
-Modules can define something called an "installation profile" to help users with the installation.
-
-==== Installation profile
-
-Installation profiles are essentially lists of packages that help users with the module installation. To give a specific example, a database module could have two profiles: server and client. This helps the user to install what they need without the need of thinking about the package names. However, installation profiles are just an optional feature and users can still install packages directly.
-
-==== Updating the system
-
-Updating the system always respects user’s module choices (or lack of module) even when there are multiple (and possibly higher) versions available.
-
-If the user doesn’t enable any modules, all packages on their system get updated to the latest versions provided by the traditional base repository.
-However, if the user enables a module stream, packages get updated to the newest version provided by the module.
-
-Thanks to this mechanism, the user has better control over the versions of packages on their system while receiving updates (such as security patches) for the whole system.
-
-==== Running multiple versions using containers
-
-Modularity brings parallel availability, not parallel installability. There are other technologies i.e. linux containers or software collections that deal with this.
-
-All the steps described above can be used in a container the same way as on a traditional system. Producing up-to-date containers with multiple versions of software in an automated way is also one of the goals.
diff --git a/en-US/architecture/consuming-software/Consuming_Software.adoc b/en-US/architecture/consuming-software/Consuming_Software.adoc
new file mode 100644
index 0000000..b027715
--- /dev/null
+++ b/en-US/architecture/consuming-software/Consuming_Software.adoc
@@ -0,0 +1,61 @@
+= Consuming Software with Modularity
+
+This is a high-level overview of how users can install software with Fedora Modularity and how is it different from the traditional workflow(s).
+
+== Understanding the Delivery Channels
+
+Modular Fedora will ship with two sets of repositories:
+
+. The *traditional base repository* representing the distribution as we know it today — there are no user-visible changes in this part.
+
+. A new *modular repository*  (often referred to as the "Application Stream" or AppStream for short) including all the additional versions delivered as modules.
+
+The Modules repository will be optional for users.
+
+image::mod-doc-repositories.png[,80%,]
+
+== Consuming the traditional packages
+
+There are no changes to the traditional user experience.
+Packages from the traditional repository will be installed and updated using the same methods as before.
+Everything keeps working as it used to.
+
+== Consuming the modular packages
+
+If a user desires to use the optioanl Modular repositories in order to consume non-default versions of software, there will be some new concepts introduced in the client tooling to manage them.
+We outline these below.
+
+=== Enabling a module
+
+Enabling a module makes its packages available on the system.
+Packages delivered as part of a module always have a priority over the ones from the traditional base, regardless of their actual version.
+Packages in modules are often replacements of the ones in the traditional base.
+
+Modularity brings parallel availability, not parallel installability.
+Only one stream of a given module can be enabled on a system — so it is always clear which version gets installed.
+Installing and running multiple versions of software can be achieved by using existing technologies, such as containers.
+
+=== Installing a module
+
+To make installation easy, some modules can be also installed as a unit, without the need of enabling them first and then installing individual packages.
+Installing a module doesn’t necessarily mean installing all of its packages.
+Modules can define something called an "installation profile" to help users with the installation.
+
+==== Installation profile
+
+Installation profiles are essentially lists of packages that help users with the module installation. To give a specific example, a database module could have two profiles: server and client. This helps the user to install what they need without the need of thinking about the package names. However, installation profiles are just an optional feature and users can still install packages directly.
+
+==== Updating the system
+
+Updating the system always respects user’s module choices (or lack of module) even when there are multiple (and possibly higher) versions available.
+
+If the user doesn’t enable any modules, all packages on their system get updated to the latest versions provided by the traditional base repository.
+However, if the user enables a module stream, packages get updated to the newest version provided by the module.
+
+Thanks to this mechanism, the user has better control over the versions of packages on their system while receiving updates (such as security patches) for the whole system.
+
+==== Running multiple versions using containers
+
+Modularity brings parallel availability, not parallel installability. There are other technologies i.e. linux containers or software collections that deal with this.
+
+All the steps described above can be used in a container the same way as on a traditional system. Producing up-to-date containers with multiple versions of software in an automated way is also one of the goals.
diff --git a/en-US/architecture/consuming-software/Modular_DNF_Behavior.adoc b/en-US/architecture/consuming-software/Modular_DNF_Behavior.adoc
new file mode 100644
index 0000000..c002d4e
--- /dev/null
+++ b/en-US/architecture/consuming-software/Modular_DNF_Behavior.adoc
@@ -0,0 +1,142 @@
+= Modular DNF Behavior
+
+This page captures the key behaviors of modular DNF.
+
+== Definitions
+
+* Ursine ("bare") packages are those that are not part of any module.
+* A module's "context" is a unique hash value generated by the build
+  system to distinguish binaries built for different Fedora releases as
+  a result of stream expansion.
+  See <<module-stream-expansion>>.
+
+== General
+
+* Existing use of RPM-based operations must not change and must
+  continue to work just as they always have.
+* DNF install/update commands can be invoked by using syntax of either
+  `dnf module <command> $modspec ...` or `dnf <command> @$modspec ...`.
+* The "platform" pseudo-module cannot be explicitly enabled, installed,
+  deleted, or have its stream changed.
+* A module is specified by its name, stream, version, context, and
+  architecture (eg., "module:stream:version:context:arch").
+** If a module has a default stream defined on a system, "stream" may be
+   omitted. Otherwise, "stream" must be explicitly provided.
+** For a given "module:stream", "version" can always be omitted. If
+   "version" is not explicitly provided, the latest "version" for the
+   given "module:stream" will be chosen.
+** If the module "context" is not specified, DNF will use heuristics to
+   determine the appropriate "context".
+   See <<module-stream-expansion>>.
+** If the module "arch" is not specified, the system's base architecture
+   will be used.
+** Specifying a non-existent "module" name should fail.
+** Specifying a non-existent "stream" (for a valid "module") should fail.
+** Specifying specifying a non-existent "version"
+   (for a valid "module:stream") should fail.
+** Specifying specifying a non-existent "context"
+   (for a valid "module:stream:version") should fail.
+** Specifying a non-existent "arch"
+   (for a valid "module:stream:version:context") should fail.
+
+== System modular defaults
+
+* DNF must look for modular default stream and installation profile
+  data in the repodata of the package installation repos--which is
+  sourced from <<fedora-module-defaults-repo>> during the Fedora build
+  and release process.
+* DNF must look for _override_ data for modular default stream and
+  installation profile on the local system in
+  `/etc/dnf/modules.defaults.d/`.
+
+== Module listing
+
+* DNF must be able to list all modular content (modules, streams,
+  enabled streams, default streams, profiles, module packages,
+  profile packages).
+
+== Module enablement
+
+* Enabling a module stream makes all of its packages available on the
+  system, but does not install them.
+* At most one stream of a module may be enabled at a time on a system.
+* Enabling a different stream of a module must be confirmed by the user
+  (or "--assumeyes").
+* Enabling a different stream of a module will automatically disable
+  the old stream.
+
+== Module Auto-enablement
+
+* If an uninstalled/unenabled module has a valid default stream
+  configured, DNF will consider the default stream of the module and
+  all of its packages available for resolving dependencies--and will
+  automatically enable the default stream of that module if any packages
+  from it are installed directly or indirectly (to resolve dependencies).
+* If an uninstalled/unenabled module:stream is listed as a runtime
+  dependency of another module being installed or enabled, DNF will
+  automatically enable that dependency.
+* Once a particular stream of a module has been enabled, DNF may not
+  automatically enable a different stream.
+
+== Module/package installation
+
+* Installing a module enables the specified stream (or default stream,
+  if not specified) and installs all of the packages associated with the
+  specified profile (or "default" profile, if not specified).
+* If a module does not explicitly have a "default" profile specified it
+  its modulemd, DNF must pretend that it exists and is empty.
+  See <<mmd-spec-v2>>.
+* Each profile of a module stream must be able to be installed.
+  However, a module's profiles may conflict amongst themselves such
+  that they cannot all be installed at the same time.
+  (A hypothetical example would be a module that provides something
+  analogous to the coreutils and coreutils-single packages in different
+  profiles. The coreutils packages provide the same functionality, but
+  conflict.)
+
+== Module update
+
+* Updating a module will update all installed packages that belong to
+  the enabled module stream--regardless if the packages were installed
+  by an install profile or ad-hoc.
+
+== Module disablement
+
+* Disabling a module does not remove any packages that belong to the
+  module.
+* Disabling a module disables modules that depend on it--unless they
+  still have packages installed.
+
+== Module removal
+
+* Uninstalling a module removes all the packages that belong to the
+  module and disables it.
+* Ad-hoc removal of all packages from an installed module does not
+  disable the module.
+
+== Module locking
+
+* A locked module cannot have a different stream enabled or be
+  disabled--without first unlocking it.
+
+== Stream expansion and contexts
+
+* Packages from module contexts that do not match the current
+  transaction are disregarded.
+  See <<module-stream-expansion>>.
+
+== Other
+
+* Any package in an enabled module takes priority over any ursine RPM
+  with the same package name, regardless of which repositories those
+  modules and packages may be in.
+* If there's an ursine or modular RPM with a higher NVR than the hotfix
+  one, the ursine or modular one wins. This is to ensure new proper
+  updates override the temporary hotfix RPMs.
+
+[bibliography]
+== References
+
+* [[[mmd-spec-v2]]] https://github.com/fedora-modularity/libmodulemd/blob/master/spec.v2.yaml
+* [[[fedora-module-defaults-repo]]] https://pagure.io/releng/fedora-module-defaults
+* [[[module-stream-expansion]]] https://fedoraproject.org/wiki/Infrastructure/Factory2/Focus/StreamExpansion

