From c56ac65d195139234794b9525a1fa175e42f40a2 Mon Sep 17 00:00:00 2001
From: Adam Samalik <asamalik@redhat.com>
Date: Aug 06 2019 12:23:29 +0000
Subject: Merge #64 `Add explanation to Using Modules - Switching module streams section.`


---

diff --git a/modules/ROOT/pages/using-modules.adoc b/modules/ROOT/pages/using-modules.adoc
index d0811e7..9e567a0 100644
--- a/modules/ROOT/pages/using-modules.adoc
+++ b/modules/ROOT/pages/using-modules.adoc
@@ -34,11 +34,11 @@ Packages from other module streams can be consumed by either _enabling a module_
 
 To **enable a module stream** and make its packages available for installation, run the following command:
 
-    $ dnf module enable NAME:STREAM
+    $ sudo dnf module enable NAME:STREAM
 
 For example, to make Node.js 8 packages available for installation, run:
 
-    $ dnf module enable nodejs:8
+    $ sudo dnf module enable nodejs:8
 
 Packages from enabled module streams can be then installed by the `dnf install NAME` command.
 
@@ -46,15 +46,15 @@ Packages from enabled module streams can be then installed by the `dnf install N
 
 To install a module, use one of the following commands. Not specifying a _stream_ or a _profile_ causes DNF to choose the _default_. However, not every module has a _default stream_ or _default profile_.
 
-    $ dnf module install NAME
-    $ dnf module install NAME:STREAM
-    $ dnf module install NAME/PROFILE
-    $ dnf module install NAME:STREAM/PROFILE
+    $ sudo dnf module install NAME
+    $ sudo dnf module install NAME:STREAM
+    $ sudo dnf module install NAME/PROFILE
+    $ sudo dnf module install NAME:STREAM/PROFILE
 
 For example, to install the Node.js 8 runtime and the client tooling of the default stream of MongoDB, run:
 
-    $ dnf module install nodejs:8
-    $ dnf module install mongodb/client
+    $ sudo dnf module install nodejs:8
+    $ sudo dnf module install mongodb/client
 
 === Switching module streams
 
@@ -62,14 +62,32 @@ NOTE: Switching streams is a risky operation that might not be always supported 
 
 Switching to a different stream than the one that is installed on a system is a two-step process. First, the current stream needs to be reset causing it not to be enabled anymore — this will however keep its packages installed. Second, a new stream needs to be installed.
 
-    $ dnf module reset NAME
-    $ dnf module install NAME:STREAM
+    $ sudo dnf module reset NAME
+    $ sudo dnf module install NAME:STREAM
 
 For example, to switch from Node.js 8 to Node.js 10, run:
 
-    $ dnf module reset nodejs
-    $ dnf module install nodejs:10
+    $ sudo dnf module reset nodejs
+    $ sudo dnf module install nodejs:10
+
+When switching RPMs that are not in a profile of stream, that is a three step process. First, the current stream needs to be reset. Second, a new stream needs to be enabled. Three, the specified RPMs are synchronized on the new stream.
+
+    $ sudo dnf module reset NAME
+    $ sudo dnf module enable NAME:STREAM
+    $ sudo dnf --allowerasing distro-sync [RPM]...
+
+For example, to switch installed RPMs from Ruby 2.5 to Ruby 2.6, run:
+
+    $ sudo dnf module reset ruby
+    $ sudo dnf module enable ruby:2.6
+    $ sudo dnf --allowerasing distro-sync
+
+To switch specified RPMs rubygem-mysql2 and rubygem-pg from Ruby 2.5 to Ruby 2.6, run:
+
+    $ sudo dnf --allowerasing distro-sync rubygem-mysql2 rubygem-pg
+
+HINT: `dnf module info NAME:STREAM` Artifacts is helpful to check RPMs in a module.
 
 == Updating the system
 
-Updating a system by running the `dnf update` command causes all packages to be upgraded to their latest version provided by their module stream.
\ No newline at end of file
+Updating a system by running the `dnf update` command causes all packages to be upgraded to their latest version provided by their module stream.