From 6502f45d3a692f11d62043895da93c068a9023d4 Mon Sep 17 00:00:00 2001
From: Adam Samalik <asamalik@redhat.com>
Date: Jul 02 2019 10:34:46 +0000
Subject: [PATCH 1/2] rewrite main page to explain modularity better


---

diff --git a/modules/ROOT/assets/images/fedora-with-modularity.png b/modules/ROOT/assets/images/fedora-with-modularity.png
new file mode 100644
index 0000000..9c44e93
Binary files /dev/null and b/modules/ROOT/assets/images/fedora-with-modularity.png differ
diff --git a/modules/ROOT/assets/images/fedora-without-modularity.png b/modules/ROOT/assets/images/fedora-without-modularity.png
new file mode 100644
index 0000000..56693d3
Binary files /dev/null and b/modules/ROOT/assets/images/fedora-without-modularity.png differ
diff --git a/modules/ROOT/assets/images/modularity-appstream-overview.png b/modules/ROOT/assets/images/modularity-appstream-overview.png
deleted file mode 100644
index c288149..0000000
Binary files a/modules/ROOT/assets/images/modularity-appstream-overview.png and /dev/null differ
diff --git a/modules/ROOT/pages/index.adoc b/modules/ROOT/pages/index.adoc
index 05485ec..9779df4 100644
--- a/modules/ROOT/pages/index.adoc
+++ b/modules/ROOT/pages/index.adoc
@@ -1,49 +1,17 @@
-= What is Modularity?
+= Modularity
 
-Modularity introduces a new optional repository to Fedora called Modular (often referred to as the "Application Stream" or AppStream for short) that ships additional versions of software on independent life cycles.
-This enables users to keep their operating system up-to-date while having the right version of an application for their use case, even when the default version in the distribution changes.
+Modularity enables you to choose a particular stream (major version) of content that has been natively built and tested for your system, and to receive the right updates for it.
 
-image::modularity-appstream-overview.png[,100%,]
+That means you no longer need to enable "rawhide" repositories to get a new version of a database, or to be prevented from performing a system upgrade to a new Fedora release just because a language runtime got a major upgrade.
 
+image::fedora-without-modularity.png[,100%,]
 
-== What Problems does Modularity Solve?
+image::fedora-with-modularity.png[,100%,]
 
-=== Too fast vs. too slow
+Because the same module stream is often available to multiple Fedora releases, you can choose to consume a particular stream regardless of what Fedora release version you're running. Thanks to that, your applications and your system can be upgraded to their next major version independently from each other.
 
-Different users have different needs.
-Developers often want the latest version, and system administrators often want stability for long periods of time.
-There are many Linux distributions out there, each targeting a different audience.
-A clear example of this is Fedora and CentOS.
+== Compatibility
 
-Fedora generally ships the latest stable versions of its component packages when it is released twice per year.
-That is convenient for desktop users and developers.
-This can be an issue for Fedora servers because it is sometimes necessary to have a stable version of certain packages for a longer period, mostly because of third-party applications.
+Modularity is built to be 100% compatible with workflows that do not expect Modularity to be present.
 
-At the same time, some people consider Fedora to move too slowly and want even newer software on their system.
-Some upstreams release their software faster than twice a year, and some users want these versions as they get released.
-
-On the other hand, CentOS targets long-term stability and releases a new version once every few years.
-This is convenient for server administrators as there are fewer changes over longer periods of time.
-The issue is that some of the software gets too old for modern applications, and newer versions might be needed.
-
-In other words, it would be convenient to be able to choose some parts of the system to update infrequently, while other parts update at a faster pace.
-
-=== Outdated containers
-
-There are many container images out there.
-A large portion of them are built manually, not actively maintained, not patched with security fixes, and still used by many people.
-This is especially true for the ones using software of a different version than the distribution the container image is based on provides.
-
-If Fedora had multiple versions of software that is actively maintained and built, could we use it to produce containers?
-Could these containers get automatically rebuilt every time the packages get updated?
-
-=== Complex packager workflows
-
-Fedora contributors maintain their packages in multiple branches, one for each release.
-This is still required even when the packages are the same across releases.
-This leads to a series of manual steps associated with the build process.
-
-Could we enable packagers to maintain packages in branches that would follow the package version instead of an arbitrary distribution release version?
-Having a single branch that builds across multiple releases would save a lot of work for packagers.
-
-This is all possible with modularity!
+Default streams are provided so you only need to make choices when you want to. Your usual installation commands continue to work, automatically consuming content from the default streams.
\ No newline at end of file

From 20cc844733c266dd0c650f3881b27a64bf5eac90 Mon Sep 17 00:00:00 2001
From: Adam Samalik <asamalik@redhat.com>
Date: Jul 04 2019 18:35:28 +0000
Subject: [PATCH 2/2] add examples to the homepage


---

diff --git a/modules/ROOT/pages/index.adoc b/modules/ROOT/pages/index.adoc
index 9779df4..c331ed3 100644
--- a/modules/ROOT/pages/index.adoc
+++ b/modules/ROOT/pages/index.adoc
@@ -2,16 +2,25 @@
 
 Modularity enables you to choose a particular stream (major version) of content that has been natively built and tested for your system, and to receive the right updates for it.
 
-That means you no longer need to enable "rawhide" repositories to get a new version of a database, or to be prevented from performing a system upgrade to a new Fedora release just because a language runtime got a major upgrade.
-
 image::fedora-without-modularity.png[,100%,]
 
 image::fedora-with-modularity.png[,100%,]
 
-Because the same module stream is often available to multiple Fedora releases, you can choose to consume a particular stream regardless of what Fedora release version you're running. Thanks to that, your applications and your system can be upgraded to their next major version independently from each other.
+That means you're no longer limited to a single version of each package for a given Fedora release. And because many streams are now available in multiple Fedora releases, you can install a specific version of software regardless of what Fedora release you're running.
+
+== Examples
+
+**Scenario 1**: Some users install packages coming from a different Fedora release in order to consume a specific version of a database that is compatible with their application. But thanks to Modularity they might not need to do that anymore, because multiple versions of the database can available in each Fedora release. All they need to do is to consume the specific stream of that database right from the Fedora repositories for their system.
+
+**Scenaro 2:** There were cases when users couldn't upgrade their system to a new Fedora release because their application wouldn't function with the new version of a language runtime coming with the upgrade. Modularity can fix this problem by providing the same language versions in both Fedora releases. With that, the user can consume a specific stream of the language and keep it even when they upgrade their system. And when the application is ready for the new language version, it can be upgraded later, independently from the OS, by switching to a different stream.
 
 == Compatibility
 
-Modularity is built to be 100% compatible with workflows that do not expect Modularity to be present.
+Modularity is built to be 100% compatible with existing expectations and workflows. The installation and update experience continues to work the same way — even when there are multiple versions of packages — thanks to default streams.
+
+For example, the following two commands work the same way on systems with and without Modularity:
+
+    $ dnf install httpd
+    $ dnf update
 
-Default streams are provided so you only need to make choices when you want to. Your usual installation commands continue to work, automatically consuming content from the default streams.
\ No newline at end of file
+On systems with multiple httpd streams available, the default stream is automatically enabled and consumed. xref:using-modules.adoc[Learn more about using modules].
\ No newline at end of file

