From ea60b9d265ac3e4749ac357b2cfd2f8932a0a369 Mon Sep 17 00:00:00 2001 From: Adam Samalik Date: Jan 10 2018 10:28:12 +0000 Subject: [PATCH 1/6] add a new design section --- diff --git a/source/_themes/modularity/static/custom.css b/source/_themes/modularity/static/custom.css index dfcc06b..04771e1 100644 --- a/source/_themes/modularity/static/custom.css +++ b/source/_themes/modularity/static/custom.css @@ -30,6 +30,10 @@ html, body { height: 100%; } +dt { + margin-top: 10px; +} + div.website-header { background-color: #143c79; } diff --git a/source/design/building.rst b/source/design/building.rst new file mode 100644 index 0000000..d730a9a --- /dev/null +++ b/source/design/building.rst @@ -0,0 +1,59 @@ +Building Software +================= + + +Traditional package builds +-------------------------- + +.. figure:: img/mod-doc-trad-builds.png + :scale: 35% + +In the existing Fedora world, packages are maintained in branches that map to specific Fedora releases. Package repositories have branches e.g. "f27" for Fedora 27, "f28" for Fedora 28, etc. + +There are no changes to the existing packager workflow. Maintaining release-specific branches and using the existing commands to build them keep working. + + +Modular package builds +---------------------- + +.. figure:: img/mod-doc-stream-builds.png + :scale: 35% + +Modularity changes package branching to be version-focused. + +Branching packages according to their major version as opposed to the distribution release brings more clarity — because we can see what lives in a branch, and removes source duplication — because there is one branch per version. + +While this approach makes more sense from the software perspective, there is no longer a clear mapping of a package branch to a particular release. Modules are a way of defining this. + +Building one source for multiple releases +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. figure:: img/mod-doc-build-more-releases.png + :scale: 35% + +Modules define what package branches are built for which Fedora releases. One module can be built against multiple releases. + +The above example produces three different binaries, one for each release. In case there are multiple architectures, three binaries will be produced for each one. + + +Building multiple versions +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. figure:: img/mod-doc-build-more-versions.png + :scale: 35% + +Multiple versions of packages can be built for one release by defining multiple modules. Users are able to choose which version they want to use on their system. + +The above example produces two different binaries, each with a different Python version. Again, in case there are multiple architectures, two binaries will be produced for each one. + +Modularity also leverages existing technologies such as containers to enable users to run multiple versions at the same time. + +Building against multiple versions +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. figure:: img/mod-doc-build-matrix.png + :scale: 35% + +Modules can be also built against other modules to achieve more complex results. Client tooling always makes sure the right version is installed for a given context. + +The above example produces two different binaries, each bind to a different Python version. Again, in case there are multiple architectures, two binaries will be produced for each one. \ No newline at end of file diff --git a/source/design/concepts.rst b/source/design/concepts.rst new file mode 100644 index 0000000..0757269 --- /dev/null +++ b/source/design/concepts.rst @@ -0,0 +1,71 @@ +Main Concepts +============= + +Modularity reuses some existing and creates some new concepts of the build and release process in Fedora. + + +Packages +-------- + +.. figure:: img/mod-doc-package.png + :scale: 35% + +We are reusing packages as they are. + +Packages are the smalest unit of software delivery. Right now, Fedora uses RPM packages to build and ship all of its software. There is a distinction between source RPM (SRPM) packages and binary RPM packages. + +As the name suggests, **source packages** contain the source code, but also the build process definition including a list of build dependencies. Building a source package results in one or multiple binary packages. + +**Binary package** is produced by building a source package in a build environment called **buildroot**. Different buildroots produce different binary packages. This means that a source package without a context is not a complete definition of a resulting binary package. + +Every Fedora release has its own buildroot. Even when multiple releases contain the same package using the same source, they are built multiple times, once in each buildroot, producing different (and often incompatible) binary packages. + +Packages are either a part of a release, or a part a module. + + +Releases +-------- + +.. figure:: img/mod-doc-release.png + :scale: 35% + +Releases are the OS generations of Fedora e.g. "Fedora 28", "Fedora 29", or "epel 7". + +Each release can only contain one major version of every package. In general, Fedora tends to ship the latest stable versions of software available. At the same time, packages need to maintain a certain API/ABI stability throughout the **lifecycle** of the release they are part of. + +The problem with this approach is finding the right balance of being **too fast vs. too slow**. For example, developers in general tend to prefer the newest versions of software, while server administrators want API/ABI stability for a longer period of time. This problem is solved by **Modules**. + + +Modules and Streams +------------------- + +.. figure:: img/mod-doc-module.png + :scale: 35% + +Modules are **collections of packages** representing a logical unit e.g. an application, a language stack, a set of tools. These packages are built, tested, and released together. + +Each module defines its **own lifecycle** which is closer to the upstream rather than the Fedora release. + +Modules are the mechanism of delivering multiple **streams** (versions) of software for the same release. This also works the other way round, the same stream for multiple releases. + +.. figure:: img/mod-doc-stream.png + :scale: 35% + +A stream is **a series of versions** having a goal such as **backwards API/ABI compatibility** or delivering the latest stable version. A "nodejs" interpreter can have streams such as "6" or "8", but also "devel" or "latest". Some packages don't have a major version. An example could be the "calc" package that is being developed in two branches "stable" and "unstable". + +Simply put, streams are the mechanism of delivering and updating software at different speeds, allowing developers to have a bleeding-edge software, and server admins longer stability. + + +Artifacts +--------- + +.. figure:: img/mod-doc-artifact.png + :scale: 35% + +Artifacts are **consumable outputs** of the build and release process e.g. an iso image, an RPM repository, a container base image, or an ostree tree. + +Each release has associated multiple artifacts with it e.g. Fedora 28 install DVD, Fedora 28 updates repository, etc. + +Modules will be delivered as an RPM repository that will work on top of existing releases. This repository will also be available in the Fedora container base image, enabling users to build containers with multiple versions of software. + + diff --git a/source/design/img/mod-doc-artifact.png b/source/design/img/mod-doc-artifact.png new file mode 100644 index 0000000..efb6c7e Binary files /dev/null and b/source/design/img/mod-doc-artifact.png differ diff --git a/source/design/img/mod-doc-build-matrix.png b/source/design/img/mod-doc-build-matrix.png new file mode 100644 index 0000000..8f58a39 Binary files /dev/null and b/source/design/img/mod-doc-build-matrix.png differ diff --git a/source/design/img/mod-doc-build-more-releases.png b/source/design/img/mod-doc-build-more-releases.png new file mode 100644 index 0000000..63f7e92 Binary files /dev/null and b/source/design/img/mod-doc-build-more-releases.png differ diff --git a/source/design/img/mod-doc-build-more-versions.png b/source/design/img/mod-doc-build-more-versions.png new file mode 100644 index 0000000..0869c97 Binary files /dev/null and b/source/design/img/mod-doc-build-more-versions.png differ diff --git a/source/design/img/mod-doc-module.png b/source/design/img/mod-doc-module.png new file mode 100644 index 0000000..446c0fb Binary files /dev/null and b/source/design/img/mod-doc-module.png differ diff --git a/source/design/img/mod-doc-package.png b/source/design/img/mod-doc-package.png new file mode 100644 index 0000000..97c207a Binary files /dev/null and b/source/design/img/mod-doc-package.png differ diff --git a/source/design/img/mod-doc-release.png b/source/design/img/mod-doc-release.png new file mode 100644 index 0000000..ab9570d Binary files /dev/null and b/source/design/img/mod-doc-release.png differ diff --git a/source/design/img/mod-doc-repositories.png b/source/design/img/mod-doc-repositories.png new file mode 100644 index 0000000..a418ca0 Binary files /dev/null and b/source/design/img/mod-doc-repositories.png differ diff --git a/source/design/img/mod-doc-stream-builds.png b/source/design/img/mod-doc-stream-builds.png new file mode 100644 index 0000000..6896f32 Binary files /dev/null and b/source/design/img/mod-doc-stream-builds.png differ diff --git a/source/design/img/mod-doc-stream.png b/source/design/img/mod-doc-stream.png new file mode 100644 index 0000000..5fe990f Binary files /dev/null and b/source/design/img/mod-doc-stream.png differ diff --git a/source/design/img/mod-doc-trad-builds.png b/source/design/img/mod-doc-trad-builds.png new file mode 100644 index 0000000..d525e25 Binary files /dev/null and b/source/design/img/mod-doc-trad-builds.png differ diff --git a/source/design/intro.rst b/source/design/intro.rst new file mode 100644 index 0000000..5a8aab3 --- /dev/null +++ b/source/design/intro.rst @@ -0,0 +1,29 @@ +The Problem to be Solved +======================== + +Too fast vs. too slow +--------------------- + +Different users have different needs. Developers want the latest versions possible, system administrators want stability for longer period of time. There are many Linux distributions out there, each targetting a different audicence. A good example is Fedora and CentOS. + +Fedora ships the latest greatest and releases a new version twice a year. That is convenient for desktop users and developers. Even though many people use Fedora on a server, it is sometimes necessary to have a stable version of certain packages for a longer time, mostly because of third-party applications. + +At the same time, some people consider fedora too slow for them and want even newer runtimes on their system. Some upstreams release their software faster than twice a year. + +On the other hand, CentOS targets long-term stability and releases a new version once every few years. This is convenient for server admins as there are less changes over longer periods of time. But some of the software gets old for modern applications and newer versions of runtimes might be needed. + +In other words, it would be convenient to be able to choose some parts of the system to be slow, and other parts to be fast. Could we do that? + +Outdated containers +------------------- + +There are many containers out there. Majority 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 having software in a different version than the distribution 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. Even when the packages are the same. And there is a series of manual steps associated with the build process. + +Could we enable packagers to maintain packages in branches that would map the package version instead of an arbitrary distribution release? Having a single branch that builds accross multiple releases would save some work for packagers. \ No newline at end of file diff --git a/source/design/using.rst b/source/design/using.rst new file mode 100644 index 0000000..6333267 --- /dev/null +++ b/source/design/using.rst @@ -0,0 +1,57 @@ +Consuming Software +================== + +.. figure:: img/mod-doc-repositories.png + :scale: 35% + +Fedora will ship with two sets of repositories: + +1. **Traditional base repository** representing the distribution as we know it today — there are no user-visible changes in this part. +2. A new **Modules repository** including all the additional versions delivered as modules. + +The Modules repository will be optional for users. + +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 ways 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. + +Enabling a module +~~~~~~~~~~~~~~~~~ + +Enabling a module makes its packages available on the system. Packages delivered as part of modules modules have always a priority over the ones from the traditional base, regardless of their actual version. Packages in modules are 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 installation profiles to help users with the installation. + +Installation profile +.................... + +Installation profiles are essentialy 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 choice 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/source/docs.rst b/source/docs.rst index 09e662d..8dd63ff 100644 --- a/source/docs.rst +++ b/source/docs.rst @@ -2,49 +2,41 @@ Documentation Index =================== -.. toctree:: - :caption: Prototype - :maxdepth: 2 - - prototype/boltron - .. toctree:: :caption: Design :maxdepth: 2 - design/building-naming - design/constructing - design/versioning - - -.. toctree:: - :caption: Development - :maxdepth: 2 + design/intro + design/concepts + design/building + design/using - development/glossary - development/resources - development/building-modules - development/building-containers .. toctree:: - :caption: Infrastructure + :caption: Project :maxdepth: 2 - infrastructure/infrastructure + faq + project/get-involved .. toctree:: - :caption: Usability + :caption: Archive :maxdepth: 2 - usability/personas + prototype/boltron -.. toctree:: - :caption: Project - :maxdepth: 2 + design/building-naming + design/constructing + design/versioning - project/get-involved + development/glossary + development/resources + development/building-modules + development/building-containers + infrastructure/infrastructure + usability/personas \ No newline at end of file diff --git a/source/faq.rst b/source/faq.rst new file mode 100644 index 0000000..6bbcb02 --- /dev/null +++ b/source/faq.rst @@ -0,0 +1,65 @@ +Frequently Asked Questions (FAQ) +================================ + + +Exactly what problem are you trying to solve? +-------------- + +The "too fast vs. too slow" problem, outdated containers, and complex packaging workflow. See "The Problem to be Solved" page for more detailed information. + + +How is this different from containers? +---------------- + +This is a build step that happens before containers. + +Modularity doesn't overlap with containers, Modularity helps producing up-to-date containers. + +Parallel availability -> consume by other tech for parallel installation. + + + + +Exactly what problem are you trying to solve? + The "too fast vs. too slow" problem, outdated containers, and complex packaging workflow. See "The Problem to be Solved" page for more detailed information. + + +How is this different from containers? + This is a build step that happens before containers. + + Modularity doesn't overlap with containers, Modularity helps producing up-to-date containers. + + Parallel availability -> consume by other tech for parallel installation. + + +How does this differ from SCLs? + Modularity is about building multiple versions of packages, and making them available to users. + SCLs are about installing software in parallel using RPM. + These two don't overlap, they complement each other. You can build an SCL using Modularity. + +Can I install more versions at once? + no! + +How is this different from RPM? Why not just different repos? + Technical: DNF performance + UX: repo is a source of software, not an application + modularity brings a nicer UX + +Are you going to produce all versions? What lifecycles and versions are envisioned? + we are making the technology so the community/upstream can build more versions + we envision longer lifecycles for LTS stacks mainly for server, and devel/rolling releases of some stacks for developers + +I can just 'dnf downgrade' to get an older version.. why do we need modularity? + using an older version that is no longer maintain can be dangerous - security updates + streams are branches of packages that stick to a particular version and get updated + +Is this different from single app VMs with custom versions? + This is/helps with a single app VM with custom versions. + Same as with containers, it helps users to get the right version for their system. + + + + + + + diff --git a/source/implementation/introduction.rst b/source/implementation/introduction.rst new file mode 100644 index 0000000..99809b6 --- /dev/null +++ b/source/implementation/introduction.rst @@ -0,0 +1,4 @@ +TBD +============ + +TBD diff --git a/source/implementation/modularity-hybrid-repos-and-terminal.png b/source/implementation/modularity-hybrid-repos-and-terminal.png new file mode 100644 index 0000000..6c27c46 Binary files /dev/null and b/source/implementation/modularity-hybrid-repos-and-terminal.png differ From 92bd760c143cd6bbdf918e7f19c5a43c77926884 Mon Sep 17 00:00:00 2001 From: Adam Samalik Date: Jan 10 2018 10:38:48 +0000 Subject: [PATCH 2/6] mark outdated docs as outdated --- diff --git a/source/design/building-naming.rst b/source/design/building-naming.rst index b478382..4bf198e 100644 --- a/source/design/building-naming.rst +++ b/source/design/building-naming.rst @@ -1,4 +1,14 @@ -Building and naming modular things +.. raw:: html + + + + +[archived] Building and naming modular things ================================== We have some basic terminology confusion around modules. Is a container diff --git a/source/design/building-naming/artifact.rst b/source/design/building-naming/artifact.rst index 2deaed4..7a67704 100644 --- a/source/design/building-naming/artifact.rst +++ b/source/design/building-naming/artifact.rst @@ -1,4 +1,14 @@ -The Image or Artifact +.. raw:: html + + + + +[archived] The Image or Artifact ===================== We build stacks into *images* or other *artifacts* such as ostree trees. diff --git a/source/design/building-naming/fit-together.rst b/source/design/building-naming/fit-together.rst index 9cc0d73..31f6147 100644 --- a/source/design/building-naming/fit-together.rst +++ b/source/design/building-naming/fit-together.rst @@ -1,4 +1,14 @@ -How do these parts fit together? +.. raw:: html + + + + +[archived] How do these parts fit together? ================================ Let’s look at a couple of examples to make it (hopefully!) clear what diff --git a/source/design/building-naming/module.rst b/source/design/building-naming/module.rst index c53ebee..eca84c4 100644 --- a/source/design/building-naming/module.rst +++ b/source/design/building-naming/module.rst @@ -1,4 +1,14 @@ -The Module +.. raw:: html + + + + +[archived] The Module ========== We group these binary packages into *modules*. Note, we can pick just a diff --git a/source/design/building-naming/package.rst b/source/design/building-naming/package.rst index b66b446..6c9596a 100644 --- a/source/design/building-naming/package.rst +++ b/source/design/building-naming/package.rst @@ -1,4 +1,14 @@ -The Package +.. raw:: html + + + + +[archived] The Package =========== We can start with the familiar ''package ''and *subpackage*, *built* as diff --git a/source/design/building-naming/stack.rst b/source/design/building-naming/stack.rst index 5c74673..69a36e8 100644 --- a/source/design/building-naming/stack.rst +++ b/source/design/building-naming/stack.rst @@ -1,4 +1,14 @@ -The Stack +.. raw:: html + + + + +[archived] The Stack ========= We can then combine modules into *stacks*. diff --git a/source/design/constructing.rst b/source/design/constructing.rst index 062bcce..ba9abf4 100644 --- a/source/design/constructing.rst +++ b/source/design/constructing.rst @@ -1,4 +1,14 @@ -Constructing a modular distribution +.. raw:: html + + + + +[archived] Constructing a modular distribution =================================== The fundamental objective of the diff --git a/source/design/constructing/back-together.rst b/source/design/constructing/back-together.rst index 5d01ebe..7450687 100644 --- a/source/design/constructing/back-together.rst +++ b/source/design/constructing/back-together.rst @@ -1,4 +1,14 @@ -Putting it all back together +.. raw:: html + + + + +[archived] Putting it all back together ============================ We need the flexibility of a smaller, more modular distribution that can diff --git a/source/design/constructing/breaking-down.rst b/source/design/constructing/breaking-down.rst index 72c0d37..e4cb4bd 100644 --- a/source/design/constructing/breaking-down.rst +++ b/source/design/constructing/breaking-down.rst @@ -1,4 +1,14 @@ -Breaking down the monolithic release +.. raw:: html + + + + +[archived] Breaking down the monolithic release ==================================== We have many steps in the release pipeline today: starting with bugzilla diff --git a/source/design/constructing/compose-distribution.rst b/source/design/constructing/compose-distribution.rst index b1ed9f5..e787b59 100644 --- a/source/design/constructing/compose-distribution.rst +++ b/source/design/constructing/compose-distribution.rst @@ -1,4 +1,14 @@ -Incremental compose of the distribution +.. raw:: html + + + + +[archived] Incremental compose of the distribution ======================================= **1. Break the distribution into distinct modules** diff --git a/source/design/versioning.rst b/source/design/versioning.rst index ac21bfc..23400d7 100644 --- a/source/design/versioning.rst +++ b/source/design/versioning.rst @@ -1,4 +1,14 @@ -Module versioning and branching +.. raw:: html + + + + +[archived] Module versioning and branching =============================== The primary core principle of Modularity is that our content should be diff --git a/source/design/versioning/coherency.rst b/source/design/versioning/coherency.rst index a55224e..9db8a0a 100644 --- a/source/design/versioning/coherency.rst +++ b/source/design/versioning/coherency.rst @@ -1,4 +1,14 @@ -Coherency of branching +.. raw:: html + + + + +[archived] Coherency of branching ====================== There are many advantages to be had in a single, coherent view of the diff --git a/source/design/versioning/constraints.rst b/source/design/versioning/constraints.rst index fbc409d..cf6fd6e 100644 --- a/source/design/versioning/constraints.rst +++ b/source/design/versioning/constraints.rst @@ -1,4 +1,14 @@ -Constraints on branching +.. raw:: html + + + + +[archived] Constraints on branching ======================== Everything so far seems to say “branching is hard, let’s not assume what it diff --git a/source/design/versioning/managing.rst b/source/design/versioning/managing.rst index 17806d4..0497f7d 100644 --- a/source/design/versioning/managing.rst +++ b/source/design/versioning/managing.rst @@ -1,4 +1,14 @@ -Managing this branching complexity +.. raw:: html + + + + +[archived] Managing this branching complexity ================================== Given that the exact branching policy for a module is currently diff --git a/source/design/versioning/properties.rst b/source/design/versioning/properties.rst index 78985dc..ba46cf7 100644 --- a/source/design/versioning/properties.rst +++ b/source/design/versioning/properties.rst @@ -1,4 +1,14 @@ -Properties of branches and update streams +.. raw:: html + + + + +[archived] Properties of branches and update streams ========================================= **ABI Compatibility:** Updates within a single update stream are likely diff --git a/source/design/versioning/terminology.rst b/source/design/versioning/terminology.rst index 1e6b142..afefbd7 100644 --- a/source/design/versioning/terminology.rst +++ b/source/design/versioning/terminology.rst @@ -1,4 +1,14 @@ -Basic branching terminology +.. raw:: html + + + + +[archived] Basic branching terminology =========================== First, though, note that the very word “version” is overloaded here. It diff --git a/source/development/building-containers.rst b/source/development/building-containers.rst index 80d2494..7b81bc6 100644 --- a/source/development/building-containers.rst +++ b/source/development/building-containers.rst @@ -1,4 +1,14 @@ -Building Containers +.. raw:: html + + + + +[archived] Building Containers =================== .. rubric:: TOC diff --git a/source/development/building-containers/containers-infra.rst b/source/development/building-containers/containers-infra.rst index 3cf58f7..6dffe5e 100644 --- a/source/development/building-containers/containers-infra.rst +++ b/source/development/building-containers/containers-infra.rst @@ -1,4 +1,14 @@ -Building containers in Fedora +.. raw:: html + + + + +[archived] Building containers in Fedora ============================= Your Dockerfile needs to be formally reviewed before becoming a part of Fedora. diff --git a/source/development/building-containers/containers-local.rst b/source/development/building-containers/containers-local.rst index abcc368..ac45a74 100644 --- a/source/development/building-containers/containers-local.rst +++ b/source/development/building-containers/containers-local.rst @@ -1,4 +1,14 @@ -Building containers locally +.. raw:: html + + + + +[archived] Building containers locally =========================== When you have your module built, let's put it in a container, so we can diff --git a/source/development/building-containers/standalone-containers.rst b/source/development/building-containers/standalone-containers.rst index 93e17ce..efcf3ce 100644 --- a/source/development/building-containers/standalone-containers.rst +++ b/source/development/building-containers/standalone-containers.rst @@ -1,4 +1,14 @@ -Standalone containers +.. raw:: html + + + + +[archived] Standalone containers ===================== diff --git a/source/development/building-modules.rst b/source/development/building-modules.rst index 1897e03..d1b53ef 100644 --- a/source/development/building-modules.rst +++ b/source/development/building-modules.rst @@ -1,4 +1,14 @@ -Building Modules +.. raw:: html + + + + +[archived] Building Modules ================ Historically, all packages in Fedora have followed the same branching structure diff --git a/source/development/building-modules/adding-modules-to-fedora.rst b/source/development/building-modules/adding-modules-to-fedora.rst index d54548e..4902321 100644 --- a/source/development/building-modules/adding-modules-to-fedora.rst +++ b/source/development/building-modules/adding-modules-to-fedora.rst @@ -1,4 +1,14 @@ -Adding modules to Fedora +.. raw:: html + + + + +[archived] Adding modules to Fedora ======================== The `packaging guidelines for modules diff --git a/source/development/building-modules/branch-naming.rst b/source/development/building-modules/branch-naming.rst index 05ff07e..9cce3ef 100644 --- a/source/development/building-modules/branch-naming.rst +++ b/source/development/building-modules/branch-naming.rst @@ -1,5 +1,14 @@ -============= -Branch Naming in dist-git Guidelines (proposed) +.. raw:: html + + + + +[archived] Branch Naming in dist-git Guidelines (proposed) ============= RPM branch naming diff --git a/source/development/building-modules/building-infra.rst b/source/development/building-modules/building-infra.rst index c9bf5ef..f9d188d 100644 --- a/source/development/building-modules/building-infra.rst +++ b/source/development/building-modules/building-infra.rst @@ -1,4 +1,14 @@ -Building modules in Fedora +.. raw:: html + + + + +[archived] Building modules in Fedora ========================== Module builds in Fedora are currently managed by fedpkg. diff --git a/source/development/building-modules/building-local.rst b/source/development/building-modules/building-local.rst index bcf2d26..80bc043 100644 --- a/source/development/building-modules/building-local.rst +++ b/source/development/building-modules/building-local.rst @@ -1,4 +1,14 @@ -Building modules locally +.. raw:: html + + + + +[archived] Building modules locally ============================ To build a modulemd, you need to have the diff --git a/source/development/building-modules/developing.rst b/source/development/building-modules/developing.rst index e396962..80f5eb4 100644 --- a/source/development/building-modules/developing.rst +++ b/source/development/building-modules/developing.rst @@ -1,4 +1,14 @@ -Defining modules (using modulemd) +.. raw:: html + + + + +[archived] Defining modules (using modulemd) ================================= To have your module build, you need to write a `modulemd diff --git a/source/development/building-modules/installation-dependency-issues.rst b/source/development/building-modules/installation-dependency-issues.rst index 0e52dc1..5d93fc1 100644 --- a/source/development/building-modules/installation-dependency-issues.rst +++ b/source/development/building-modules/installation-dependency-issues.rst @@ -1,7 +1,14 @@ +.. raw:: html -.. _resolving-dependency-issues: + -Examining dependency issues during the installation of modules + +[archived] Examining dependency issues during the installation of modules ============================================================== A common problem while installing a module is that one or more of its diff --git a/source/development/building-modules/naming-policy.rst b/source/development/building-modules/naming-policy.rst index 3944ca3..9169d47 100644 --- a/source/development/building-modules/naming-policy.rst +++ b/source/development/building-modules/naming-policy.rst @@ -1,5 +1,14 @@ -============= -Naming Policy +.. raw:: html + + + + +[archived] Naming Policy ============= This document defines naming policy for modulemd metadata of final (built) modules. This policy does **NOT** apply on sources such as modulemd yaml in dist-git. diff --git a/source/development/building-modules/testing.rst b/source/development/building-modules/testing.rst index e5176f2..733202f 100644 --- a/source/development/building-modules/testing.rst +++ b/source/development/building-modules/testing.rst @@ -1,4 +1,14 @@ -Testing modular content in Fedora +.. raw:: html + + + + +[archived] Testing modular content in Fedora ================================= Interactive Testing diff --git a/source/development/glossary.rst b/source/development/glossary.rst index c8de9cd..388bbe1 100644 --- a/source/development/glossary.rst +++ b/source/development/glossary.rst @@ -1,4 +1,14 @@ -Glossary +.. raw:: html + + + + +[archived] Glossary ======== Definitions of key terms and concepts for the Modular Fedora project. diff --git a/source/development/resources.rst b/source/development/resources.rst index a81159b..54eb98f 100644 --- a/source/development/resources.rst +++ b/source/development/resources.rst @@ -1,4 +1,14 @@ -Resources +.. raw:: html + + + + +[archived] Resources ========= This page lists our Git repositories and other resources we use. diff --git a/source/infrastructure/infrastructure.rst b/source/infrastructure/infrastructure.rst index b338378..98657d9 100644 --- a/source/infrastructure/infrastructure.rst +++ b/source/infrastructure/infrastructure.rst @@ -1,4 +1,14 @@ -Infrastructure +.. raw:: html + + + + +[archived] Infrastructure ============== Modularity will be built using the `Factory 2.0, documented on the Fedora diff --git a/source/prototype/boltron.rst b/source/prototype/boltron.rst index a227904..40d38ac 100644 --- a/source/prototype/boltron.rst +++ b/source/prototype/boltron.rst @@ -1,4 +1,14 @@ -Fedora 26 Boltron Server +.. raw:: html + + + + +[archived] Fedora 26 Boltron Server ======================== diff --git a/source/prototype/boltron/content.rst b/source/prototype/boltron/content.rst index bdc5306..ba40454 100644 --- a/source/prototype/boltron/content.rst +++ b/source/prototype/boltron/content.rst @@ -1,4 +1,14 @@ -Boltron Content +.. raw:: html + + + + +[archived] Boltron Content =============== The following is a list of modules that we have completed. Many of the diff --git a/source/prototype/boltron/feedback.rst b/source/prototype/boltron/feedback.rst index 07f60a7..8ef884e 100644 --- a/source/prototype/boltron/feedback.rst +++ b/source/prototype/boltron/feedback.rst @@ -1,4 +1,14 @@ -Boltron Feedback +.. raw:: html + + + + +[archived] Boltron Feedback ================ Give Feedback diff --git a/source/prototype/boltron/instructions.rst b/source/prototype/boltron/instructions.rst index 90c940d..5249954 100644 --- a/source/prototype/boltron/instructions.rst +++ b/source/prototype/boltron/instructions.rst @@ -1,4 +1,14 @@ -Boltron Instructions +.. raw:: html + + + + +[archived] Boltron Instructions ==================== Boltron is shipped as a container image. Use the following commands to pull diff --git a/source/prototype/boltron/issues.rst b/source/prototype/boltron/issues.rst index 0350466..0270274 100644 --- a/source/prototype/boltron/issues.rst +++ b/source/prototype/boltron/issues.rst @@ -1,4 +1,14 @@ -Known Issues +.. raw:: html + + + + +[archived] Known Issues ============ Please see the Modularity issue tracker below to see and report issues. diff --git a/source/usability/personas.rst b/source/usability/personas.rst index 31655b5..b5f8219 100644 --- a/source/usability/personas.rst +++ b/source/usability/personas.rst @@ -1,4 +1,14 @@ -Personas +.. raw:: html + + + + +[archived] Personas ======== The information below relates to personas developed for the use of the From d5bdff5f5ae51e38760f76f5c4334fc60f849717 Mon Sep 17 00:00:00 2001 From: Adam Samalik Date: Jan 10 2018 11:02:38 +0000 Subject: [PATCH 3/6] update FAQ --- diff --git a/source/faq.rst b/source/faq.rst index 6bbcb02..3bc8a96 100644 --- a/source/faq.rst +++ b/source/faq.rst @@ -3,59 +3,47 @@ Frequently Asked Questions (FAQ) Exactly what problem are you trying to solve? --------------- - -The "too fast vs. too slow" problem, outdated containers, and complex packaging workflow. See "The Problem to be Solved" page for more detailed information. + The "too fast vs. too slow" problem, outdated containers, and complex packaging workflow. See :doc:`/design/intro` page for more detailed information. How is this different from containers? ----------------- + This is a build step that happens before containers. -This is a build step that happens before containers. + Modularity provides parallel availability of multiple versions that can be consumed by containers to enable parallel installation. -Modularity doesn't overlap with containers, Modularity helps producing up-to-date containers. -Parallel availability -> consume by other tech for parallel installation. +How does this differ from SCLs? + Modularity is about building multiple versions of packages, and making them available to users. + + SCLs are about installing software in parallel using RPM. + + These two don't overlap, they complement each other. You can build an SCL using Modularity. +Can I install more versions at once + Modularity does not invent a new technology for parallel installation. Existing solution such as containers can be used to achieve this. -Exactly what problem are you trying to solve? - The "too fast vs. too slow" problem, outdated containers, and complex packaging workflow. See "The Problem to be Solved" page for more detailed information. +How is this different from RPM? Why not just different repos? + Technical: DNF performance with many repositories. We envision having tens or even hundreds of modules available to a single system. + User experience: A repository is a source of software provided by a vendor, not necessarily representing a single application, language stack, or any other logical unit of software. A repository typically contains multiple applications, stacks, etc. We do not want to change this concept. -How is this different from containers? - This is a build step that happens before containers. - - Modularity doesn't overlap with containers, Modularity helps producing up-to-date containers. - - Parallel availability -> consume by other tech for parallel installation. +Are you going to produce all versions? What lifecycles and versions are envisioned? + We are developing the technology such as the build pipelina and client tooling to enable contributors to build multiple versions. -How does this differ from SCLs? - Modularity is about building multiple versions of packages, and making them available to users. - SCLs are about installing software in parallel using RPM. - These two don't overlap, they complement each other. You can build an SCL using Modularity. + We envision longer lifecycles for LTS stacks mainly for server, and devel/rolling releases of some stacks for developers. -Can I install more versions at once? - no! -How is this different from RPM? Why not just different repos? - Technical: DNF performance - UX: repo is a source of software, not an application - modularity brings a nicer UX +I can just 'dnf downgrade' to get an older version.. why do we need modularity? + Using an older version that is no longer maintain can be dangerous, mostly because of the lack of security updates. -Are you going to produce all versions? What lifecycles and versions are envisioned? - we are making the technology so the community/upstream can build more versions - we envision longer lifecycles for LTS stacks mainly for server, and devel/rolling releases of some stacks for developers + Modules, on the other hand, represent a major version that is still being actively maintained by the upstream and therefore should receive updates. -I can just 'dnf downgrade' to get an older version.. why do we need modularity? - using an older version that is no longer maintain can be dangerous - security updates - streams are branches of packages that stick to a particular version and get updated Is this different from single app VMs with custom versions? - This is/helps with a single app VM with custom versions. - Same as with containers, it helps users to get the right version for their system. + This helps with a single app VM with custom versions. Same as with containers, it helps users to get the right version for their system. From 51c612440ab44dad83a059f6a01d2fb777a34c03 Mon Sep 17 00:00:00 2001 From: Adam Samalik Date: Jan 11 2018 13:24:35 +0000 Subject: [PATCH 4/6] fix a few typos --- diff --git a/source/design/concepts.rst b/source/design/concepts.rst index 0757269..7619cee 100644 --- a/source/design/concepts.rst +++ b/source/design/concepts.rst @@ -12,7 +12,7 @@ Packages We are reusing packages as they are. -Packages are the smalest unit of software delivery. Right now, Fedora uses RPM packages to build and ship all of its software. There is a distinction between source RPM (SRPM) packages and binary RPM packages. +Packages are the smallest unit of software delivery. Right now, Fedora uses RPM packages to build and ship all of its software. There is a distinction between source RPM (SRPM) packages and binary RPM packages. As the name suggests, **source packages** contain the source code, but also the build process definition including a list of build dependencies. Building a source package results in one or multiple binary packages. diff --git a/source/design/intro.rst b/source/design/intro.rst index 5a8aab3..f741ebd 100644 --- a/source/design/intro.rst +++ b/source/design/intro.rst @@ -4,7 +4,7 @@ The Problem to be Solved Too fast vs. too slow --------------------- -Different users have different needs. Developers want the latest versions possible, system administrators want stability for longer period of time. There are many Linux distributions out there, each targetting a different audicence. A good example is Fedora and CentOS. +Different users have different needs. Developers want the latest versions possible, system administrators want stability for longer period of time. There are many Linux distributions out there, each targetting a different audience. A good example is Fedora and CentOS. Fedora ships the latest greatest and releases a new version twice a year. That is convenient for desktop users and developers. Even though many people use Fedora on a server, it is sometimes necessary to have a stable version of certain packages for a longer time, mostly because of third-party applications. @@ -26,4 +26,4 @@ Complex packager workflows Fedora contributors maintain their packages in multiple branches — one for each release. Even when the packages are the same. And there is a series of manual steps associated with the build process. -Could we enable packagers to maintain packages in branches that would map the package version instead of an arbitrary distribution release? Having a single branch that builds accross multiple releases would save some work for packagers. \ No newline at end of file +Could we enable packagers to maintain packages in branches that would map the package version instead of an arbitrary distribution release? Having a single branch that builds across multiple releases would save some work for packagers. \ No newline at end of file diff --git a/source/design/using.rst b/source/design/using.rst index 6333267..3f5ffac 100644 --- a/source/design/using.rst +++ b/source/design/using.rst @@ -37,7 +37,7 @@ To make installation easy, some modules can be also installed as a unit, without Installation profile .................... -Installation profiles are essentialy 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. +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 ~~~~~~~~~~~~~~~~~~~ diff --git a/source/faq.rst b/source/faq.rst index 3bc8a96..b5cdae8 100644 --- a/source/faq.rst +++ b/source/faq.rst @@ -31,7 +31,7 @@ How is this different from RPM? Why not just different repos? Are you going to produce all versions? What lifecycles and versions are envisioned? - We are developing the technology such as the build pipelina and client tooling to enable contributors to build multiple versions. + We are developing the technology such as the build pipeline and client tooling to enable contributors to build multiple versions. We envision longer lifecycles for LTS stacks mainly for server, and devel/rolling releases of some stacks for developers. From 456ee73a06562d8c92e278975d1b23bfe1ce5c39 Mon Sep 17 00:00:00 2001 From: Adam Samalik Date: Jan 11 2018 13:28:02 +0000 Subject: [PATCH 5/6] make archive look nicer --- diff --git a/source/archive.rst b/source/archive.rst new file mode 100644 index 0000000..cc46892 --- /dev/null +++ b/source/archive.rst @@ -0,0 +1,20 @@ +Archive +======= + +.. toctree:: + :maxdepth: 1 + + prototype/boltron + + design/building-naming + design/constructing + design/versioning + + development/glossary + development/resources + development/building-modules + development/building-containers + + infrastructure/infrastructure + + usability/personas \ No newline at end of file diff --git a/source/docs.rst b/source/docs.rst index 8dd63ff..c1e0a16 100644 --- a/source/docs.rst +++ b/source/docs.rst @@ -26,17 +26,4 @@ Documentation Index :caption: Archive :maxdepth: 2 - prototype/boltron - - design/building-naming - design/constructing - design/versioning - - development/glossary - development/resources - development/building-modules - development/building-containers - - infrastructure/infrastructure - - usability/personas \ No newline at end of file + archive \ No newline at end of file From de01adc8f4c945052067f3da3116e74a69dff365 Mon Sep 17 00:00:00 2001 From: Adam Samalik Date: Jan 15 2018 09:49:10 +0000 Subject: [PATCH 6/6] rephrase some bits by applying a PR feedback --- diff --git a/source/archive.rst b/source/archive.rst index cc46892..d8a6387 100644 --- a/source/archive.rst +++ b/source/archive.rst @@ -14,6 +14,8 @@ Archive development/resources development/building-modules development/building-containers + development/integration/coding-style-python + development/integration/grooming infrastructure/infrastructure diff --git a/source/design/intro.rst b/source/design/intro.rst index f741ebd..391578c 100644 --- a/source/design/intro.rst +++ b/source/design/intro.rst @@ -6,13 +6,13 @@ Too fast vs. too slow Different users have different needs. Developers want the latest versions possible, system administrators want stability for longer period of time. There are many Linux distributions out there, each targetting a different audience. A good example is Fedora and CentOS. -Fedora ships the latest greatest and releases a new version twice a year. That is convenient for desktop users and developers. Even though many people use Fedora on a server, it is sometimes necessary to have a stable version of certain packages for a longer time, mostly because of third-party applications. +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. Even though many people use Fedora on a server, it is sometimes necessary to have a stable version of certain packages for a longer time, mostly because of third-party applications. -At the same time, some people consider fedora too slow for them and want even newer runtimes on their system. Some upstreams release their software faster than twice a year. +At the same time, some people consider Fedora to be moving too slow for them and want even newer runtimes on their system. Some upstreams release their software faster than twice a year. -On the other hand, CentOS targets long-term stability and releases a new version once every few years. This is convenient for server admins as there are less changes over longer periods of time. But some of the software gets old for modern applications and newer versions of runtimes might be needed. +On the other hand, CentOS targets long-term stability and releases a new version once every few years. This is convenient for server admins as there are fewer changes over longer periods of time. But some of the software gets old for modern applications and newer versions of runtimes might be needed. -In other words, it would be convenient to be able to choose some parts of the system to be slow, and other parts to be fast. Could we do that? +In other words, it would be convenient to be able to choose some parts of the system to be moving slow, and other parts to be moving fast. Could we do that? Outdated containers ------------------- diff --git a/source/project/get-involved.rst b/source/project/get-involved.rst index 7432251..ad99442 100644 --- a/source/project/get-involved.rst +++ b/source/project/get-involved.rst @@ -68,9 +68,3 @@ Integration of changes In order so that our code base is always clean and maintainable, we have to enforce certain rules on how code is written or formatted, how changes are broken up into commits and how pull requests are handled. - -.. toctree:: - :maxdepth: 1 - - ../development/integration/coding-style-python - ../development/integration/grooming