From 4d7dabe3f52fd567b86a9c1dd8f0991ff22c7376 Mon Sep 17 00:00:00 2001 From: Nils Philippsen Date: Jul 26 2017 09:10:35 +0000 Subject: [PATCH 1/5] avoid (most) excessively long lines --- diff --git a/README.md b/README.md index 548fa23..16ebbcb 100644 --- a/README.md +++ b/README.md @@ -4,11 +4,13 @@ Hosted at [docs.pagure.org/modularity/](https://docs.pagure.org/modularity/) ## Contributing -If you want to change anything in the docs, please send a pull-request to this repo. Someone from the Modularity team will review and push your changes. +If you want to change anything in the docs, please send a pull-request to this +repo. Someone from the Modularity team will review and push your changes. ## Local Preview -The website is using Python Sphinx. To build it locally, install the necessary packages: +The website is using Python Sphinx. To build it locally, install the necessary +packages: ``` $ sudo dnf install python3-sphinx make diff --git a/source/_themes/modularity/boltron/index.html b/source/_themes/modularity/boltron/index.html index f1b505e..dce82ba 100644 --- a/source/_themes/modularity/boltron/index.html +++ b/source/_themes/modularity/boltron/index.html @@ -10,25 +10,41 @@ -
+

Boltron is here!

-

We have built the first modular prototype - Fedora 26 Boltron Server!

+

We have built the first modular prototype - + Fedora 26 Boltron Server!

Download and try Boltron

-

Boltron is available as many artifacts including a container image, iso, and a qcow image.

- Try Boltron +

Boltron is available as many artifacts including a container image, + iso, and a qcow image.

+ Try Boltron
@@ -37,8 +53,19 @@

There are 25 modules for you to play with

-

The following is a list of 25 modules included in Boltron. Many of them are also built as containers.

+

The following is a list of 25 modules included in Boltron. + Many of them are also built as containers.

+
  • base-runtime-f26
    • @@ -72,17 +99,23 @@
  • varnish-f26
- Learn about Boltron content + Learn about Boltron content

We would love to hear your feedback!

-

You can give us either general Modularity feedback or try the walkthrough for more detailed and UX feedback.

+

You can give us either general Modularity feedback or try the + walkthrough for more detailed and UX feedback.

- General feedback - Walkthrough and UX feedback + + General feedback + + + Walkthrough and UX feedback +

@@ -90,8 +123,13 @@

Watch the videos

-

There is a series of videos coming out on YouTube that will help you get started with Boltron. See our Fedora Modularity YouTube channel.

- Boltron on Youtube +

There is a series of videos coming out on YouTube that will + help you get started with Boltron. See our + + Fedora Modularity YouTube channel + .

+ + Boltron on Youtube
diff --git a/source/_themes/modularity/index.html b/source/_themes/modularity/index.html index bbe2624..c29c6b8 100644 --- a/source/_themes/modularity/index.html +++ b/source/_themes/modularity/index.html @@ -10,9 +10,21 @@
@@ -21,15 +33,22 @@

Building a modular Linux OS

with multiple versions of components on different lifecycles.

-

Read the Docs

+

+ Read the Docs +

Boltron is here!

-

We have built the first modular prototype - Fedora 26 Boltron Server!

-

Learn more about Boltron

+

We have built the first modular prototype - + Fedora 26 Boltron Server!

+

+ Learn more about Boltron +

@@ -47,8 +66,11 @@

Moving focus from packages to components

-

Modularity splits the Linux distribution into smaller pieces called modules.
- Modules are provided in multiple streams and on independent lifecycles.

+

+ Modularity splits the Linux distribution into smaller pieces + called modules.
+ Modules are provided in multiple streams and on + independent lifecycles.

@@ -59,8 +81,10 @@

Giving users choice and packagers flexibility

-

Modules come in different streams with independent lifecycles.
- Streams have different goals - specific version, stability, or following upstream.

+

Modules come in different streams with + independent lifecycles.
+ Streams have different goals - specific version, + stability, or following upstream.

@@ -68,13 +92,16 @@

Module as an ultimate build recipe

-

Packagers decide how to build - by defining components, build order, and buildroot.

+

Packagers decide how to build - by defining + components, build order, and buildroot.

-

Packagers decide what to ship - by filtering unnecessary binary packages.

+

Packagers decide what to ship - by filtering + unnecessary binary packages.

-

Packagers decide how to use - by defining a supported API and install profiles.

+

Packagers decide how to use - by defining a supported + API and install profiles.

@@ -82,25 +109,40 @@

Modules run almost everywhere

Each module can be built into multiple artifacts.
- Containers for clouds and servers, flatpaks* for desktop, RPMs for tradition.

+ Containers for clouds and servers, flatpaks* for + desktop, RPMs for tradition.

-

* Flatpaks are more future than the other two, but on the list!

+

* Flatpaks are more future than the other two, + but on the list!

Follow our progress

-

We post regular updates to our Fedora Modularity YouTube Channel.

-

Watch our videos

+

We post regular updates to our + + Fedora Modularity YouTube Channel.

+

+ Watch our videos +

Get in touch!

-

Come to our regular meeting, ask us on the mailing list, or discuss on our IRC channel.

-

Modularity Working Group wiki page

+

Come to our + + regular meeting, ask us on the + + mailing list, or discuss on our + IRC channel.

+

+ Modularity Working Group wiki page

diff --git a/source/_themes/modularity/layout.html b/source/_themes/modularity/layout.html index 6a0ae6d..55ff66c 100644 --- a/source/_themes/modularity/layout.html +++ b/source/_themes/modularity/layout.html @@ -10,9 +10,21 @@ @@ -38,7 +50,10 @@
  • {{ title }}
    • - Edit + + Edit +
    {% block body %}{% endblock %} @@ -48,14 +63,23 @@
    {% if next %} - {{ _('Next') }} + + {{ _('Next') }} + + {% else %} {% endif %} {% if prev %} - {{ _('Previous') }} + + + {{ _('Previous') }} + {% else %} - {{ _('Previous') }} + + + {{ _('Previous') }} + {% endif %}
    diff --git a/source/design/building-naming/module.rst b/source/design/building-naming/module.rst index 753b052..c53ebee 100644 --- a/source/design/building-naming/module.rst +++ b/source/design/building-naming/module.rst @@ -35,6 +35,6 @@ they both assemble existing compiled packages into bundled output; but the module compose is just one single targeted assembly, whereas the full distribution Compose typically creates multiple repositories and images as output in a single large job. Also note that we can, in theory, -perform the build (compilation) of the packages within a module, and the compose of -the module itself, as a single step; we might term this a **module +perform the build (compilation) of the packages within a module, and the +compose of the module itself, as a single step; we might term this a **module build.** diff --git a/source/design/constructing/back-together.rst b/source/design/constructing/back-together.rst index 31f48d7..5d01ebe 100644 --- a/source/design/constructing/back-together.rst +++ b/source/design/constructing/back-together.rst @@ -11,10 +11,10 @@ Example: Reproducing the traditional distribution versions Having categorised the Fedora rpms into groups and composed those package groups into distinct modules, creating what we have -traditionally called a distribution variant or edition can now be done simply by -creating a flat yum repository containing all the desired modules for -that offering. In the terminology we are using here, the output -repository is simply another output artifact. +traditionally called a distribution variant or edition can now be done simply +by creating a flat yum repository containing all the desired modules for that +offering. In the terminology we are using here, the output repository is +simply another output artifact. .. figure:: constructing-image6.png :alt: constructing-image6.png diff --git a/source/design/versioning/coherency.rst b/source/design/versioning/coherency.rst index 9ccd4c0..82ab87e 100644 --- a/source/design/versioning/coherency.rst +++ b/source/design/versioning/coherency.rst @@ -67,5 +67,5 @@ ability to drive a common branching structure across a set of modules when that is needed for product release requirements. First-class support for such a **consolidated release** is absolutely necessary; to devolve the distribution into an unmanaged, completely-uncoordinated set -of independent modules is likely unsustainable for both engineers, maintainers, and -users alike. +of independent modules is likely unsustainable for both engineers, +maintainers, and users alike. diff --git a/source/design/versioning/constraints.rst b/source/design/versioning/constraints.rst index 6d0045a..df554e7 100644 --- a/source/design/versioning/constraints.rst +++ b/source/design/versioning/constraints.rst @@ -19,8 +19,8 @@ This is something that is surprisingly common. Examples might be when we want to include a library to support our own package/application, but do not want to give it full support for end-users; we might include the library itself, but not include the components -that provide the ability to develop against it (the include files, static libraries etc. that -typically land in a -devel binary rpm). +that provide the ability to develop against it (the include files, static +libraries etc. that typically land in a -devel binary rpm). Can we do this naturally in a modular build chain? Clearly it breaks any assumption that a module can be both compiled and composed in complete diff --git a/source/development/building-modules/adding-modules-to-fedora.rst b/source/development/building-modules/adding-modules-to-fedora.rst index 16ca2a8..a867cf4 100644 --- a/source/development/building-modules/adding-modules-to-fedora.rst +++ b/source/development/building-modules/adding-modules-to-fedora.rst @@ -1,13 +1,17 @@ Adding modules to Fedora ======================== -All modules should go through a formal review - the same way as packages do - before they can become part -of Fedora. As the Modularity project is still under development and there is no review process yet, -only members of the Modularity team can add new modules trough a temporary simplified process. +All modules should go through a formal review - the same way as packages do - +before they can become part of Fedora. As the Modularity project is still +under development and there is no review process yet, only members of the +Modularity team can add new modules trough a temporary simplified process. -At the moment, the preferred way for both **production** and **staging** is to create a ticket at -`https://pagure.io/fedora-infrastructure/issues `__ -to add the new repository and give you write access. Make sure to -mention that you need a **'module**' repository, and that you need it in production or staging. +At the moment, the preferred way for both **production** and **staging** is to +create a ticket at `https://pagure.io/fedora-infrastructure/issues +`__ to add the new repository +and give you write access. Make sure to mention that you need a **'module**' +repository, and that you need it in production or staging. -The repositories will be available in the Fedora dist git - see the `httpd module `__ as an example. +The repositories will be available in the Fedora dist git - see the `httpd +module `__ as an +example. diff --git a/source/development/building-modules/building-infra.rst b/source/development/building-modules/building-infra.rst index 2b23d0b..6903739 100644 --- a/source/development/building-modules/building-infra.rst +++ b/source/development/building-modules/building-infra.rst @@ -16,7 +16,8 @@ On **Fedora rawhide** and **Fedora 26**, just install it by: $ sudo dnf install module-build-service -On **Fedora 25**, just install the latest version `https://koji.fedoraproject.org/koji/packageinfo?packageID=23564`: +On **Fedora 25**, just install the latest version +`https://koji.fedoraproject.org/koji/packageinfo?packageID=23564`: :: @@ -28,4 +29,5 @@ To build your modulemd, run a command: $ mbs-build submit -w -The command will submit build into infrastructure and watch the task, so you are able to track results. \ No newline at end of file +The command will submit build into infrastructure and watch the task, so you +are able to track results. diff --git a/source/development/building-modules/building-local.rst b/source/development/building-modules/building-local.rst index 9e12dbe..9c54e1b 100644 --- a/source/development/building-modules/building-local.rst +++ b/source/development/building-modules/building-local.rst @@ -1,7 +1,9 @@ Building modules locally ============================ -To build a modulemd, you need to have the `Module Build Service `__ installed on your system. +To build a modulemd, you need to have the +`Module Build Service `__ +installed on your system. On **Fedora rawhide** and **Fedora 26**, install it by: @@ -9,7 +11,8 @@ On **Fedora rawhide** and **Fedora 26**, install it by: $ sudo dnf install module-build-service -On **Fedora 25**, install the latest version from `https://koji.fedoraproject.org/koji/packageinfo?packageID=23564`: +On **Fedora 25**, install the latest version from +`https://koji.fedoraproject.org/koji/packageinfo?packageID=23564`: :: diff --git a/source/development/building-modules/containers-infra.rst b/source/development/building-modules/containers-infra.rst index c84d85d..2655071 100644 --- a/source/development/building-modules/containers-infra.rst +++ b/source/development/building-modules/containers-infra.rst @@ -8,7 +8,8 @@ There are two ways to build a Docker container image in Fedora infrastructure: #. **In production environment** -- the process starts by initiating a - review request, as specified in `Container:Review_Process `__. + review request, as specified in `Container:Review_Process + `__. #. **In staging environment** -- this is where we can bypass the review process and iterate more quickly; In order to use staging environment, we should request creation of dist-git repo and pkgdb @@ -81,7 +82,8 @@ of available images: :: - $ curl -s https://registry.fedoraproject.org/v2/_catalog | python -m json.tool + $ curl -s https://registry.fedoraproject.org/v2/_catalog | \ + python -m json.tool { "repositories": [ "cockpit", diff --git a/source/development/building-modules/containers-local.rst b/source/development/building-modules/containers-local.rst index a5006d4..f6efcd5 100644 --- a/source/development/building-modules/containers-local.rst +++ b/source/development/building-modules/containers-local.rst @@ -2,12 +2,14 @@ Building containers locally =========================== When you have your module built, let's put it in a container, so we can -use it. As an example, we will use the `perl image `__. +use it. As an example, we will use the `perl image +`__. Module RPM repository --------------------- -First, upload your RPM repository from the previous step somewhere publicly accessible. For example, you can use Fedorapeople to host your packages: +First, upload your RPM repository from the previous step somewhere publicly +accessible. For example, you can use Fedorapeople to host your packages: :: @@ -19,13 +21,17 @@ First, upload your RPM repository from the previous step somewhere publicly acce Dockerfile ---------- -Next step will be writing a Dockerfile to build a container image with your module. +Next step will be writing a Dockerfile to build a container image with your +module. -The Base Runtime image is currently only available from Docker Hub and you can use it as your base image by specifying ``FROM /baseruntime/baseruntime``. +The Base Runtime image is currently only available from Docker Hub and you can +use it as your base image by specifying ``FROM /baseruntime/baseruntime``. -You also need to write a repo file for your module and add it to your container, so you can install the module in it. -See the example of the repo file in ``__. -The following snippet then shows how you copy the repo and install the files from it in your container: +You also need to write a repo file for your module and add it to your +container, so you can install the module in it. See the example of the repo +file in ``__. The +following snippet then shows how you copy the repo and install the files from +it in your container: :: @@ -52,5 +58,5 @@ The following snippet then shows how you copy the repo and install the files fro Building the image ------------------- -Finally, when you have your repository and Dockerfile ready, use the ``docker build --tag=`` command to -build the container image. +Finally, when you have your repository and Dockerfile ready, use the ``docker +build --tag=`` command to build the container image. diff --git a/source/development/building-modules/developing.rst b/source/development/building-modules/developing.rst index f248715..f08b6af 100644 --- a/source/development/building-modules/developing.rst +++ b/source/development/building-modules/developing.rst @@ -1,7 +1,11 @@ Defining modules in modulemd ============================ -To have your module build, you need to start with writing a `modulemd `__ file which is a definition of your module including the components, API, and all the information necessary to build your module like specifying the build root and a build order for the packages. Let’s have a look at an example Vim module: +To have your module build, you need to start with writing a `modulemd +`__ file which is a definition of your module +including the components, API, and all the information necessary to build your +module like specifying the build root and a build order for the packages. +Let’s have a look at an example Vim module: :: @@ -52,15 +56,17 @@ To have your module build, you need to start with writing a `modulemd `__. +those that are already included in `Base Runtime +`__. Here's how you can get the list of vim dependencies that are not in Base Runtime: diff --git a/source/development/building-modules/module-guidelines.rst b/source/development/building-modules/module-guidelines.rst index 9601c90..0562804 100644 --- a/source/development/building-modules/module-guidelines.rst +++ b/source/development/building-modules/module-guidelines.rst @@ -434,10 +434,10 @@ Minimal module with RPM content but with the -docs subpackage excluded ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Yet another flavour of the minimal module, containing one RPM package -with SRPM name ``foo``. A build of ``foo`` creates binary packages ``foo-1.0-1`` -and the subpackage ``foo-doc-1.0-1``. Both would get included in the -module for any architecture if no filter were be used. This module -doesn't define any dependencies or optional metadata. +with SRPM name ``foo``. A build of ``foo`` creates binary packages +``foo-1.0-1`` and the subpackage ``foo-doc-1.0-1``. Both would get included in +the module for any architecture if no filter were be used. This module doesn't +define any dependencies or optional metadata. :: @@ -558,7 +558,8 @@ included components and populate the ``data`` → ``license`` → ``content`` li Complete module definition ~~~~~~~~~~~~~~~~~~~~~~~~~~ -See the `modulemd specification `_. +See the `modulemd specification +`_. SLAs and EOLs ------------- diff --git a/source/development/building-modules/standalone-containers.rst b/source/development/building-modules/standalone-containers.rst index 3194eee..93e17ce 100644 --- a/source/development/building-modules/standalone-containers.rst +++ b/source/development/building-modules/standalone-containers.rst @@ -13,15 +13,20 @@ have to learn new commands while still being able to work with containers. Requirements ------------ -- Only a single instance of a standalone container is supported to run on a host (installation of the same container image twice won't be successful). +- Only a single instance of a standalone container is supported to run on a + host (installation of the same container image twice won't be successful). - Services are managed via systemd unit files. - Containers are installed to a system. - There is no dedicated network namespace. -- Configuration is stored in the same locations on the host as a non-containerized service. -- Persistent data can be found in the same locations on the host as for non-containerized service. -- Service presence, configuration and persistent data are tracked by the RPM database. +- Configuration is stored in the same locations on the host as a + non-containerized service. +- Persistent data can be found in the same locations on the host as for + non-containerized service. +- Service presence, configuration and persistent data are tracked by the RPM + database. - Application lifecycle is close to services deployed as RPMs. -- Some commands may need to be executed inside the container since the service is not running directly on host. +- Some commands may need to be executed inside the container since the + service is not running directly on host. Quick how-to @@ -29,8 +34,9 @@ Quick how-to We utilize the atomic command to install a container image on a host. -In order to get files from a container image to the host, you should have a specific -directory structure inside your container image. Here's an example of nginx container image: +In order to get files from a container image to the host, you should have a +specific directory structure inside your container image. Here's an example +of nginx container image: :: @@ -71,9 +77,13 @@ directory structure inside your container image. Here's an example of nginx cont └── poweredby.png -- **exports** directory is what atomic uses, it is in a root of the container image -- **hostfs** is a tree of directories and files which will land on the host, tracked by a generated RPM -- a systemd unit :code:`nginx-container.service`, which controls the containerized nginx, is placed in :code:`/exports/hostfs/usr/lib/systemd/system` +- **exports** directory is what atomic uses, it is in a root of the container + image +- **hostfs** is a tree of directories and files which will land on the host, + tracked by a generated RPM +- a systemd unit :code:`nginx-container.service`, which controls the + containerized nginx, is placed in + :code:`/exports/hostfs/usr/lib/systemd/system` Here's the mentioned :code:`nginx-container.service`: @@ -100,9 +110,11 @@ Once the image is built, you can install it like this: There is no released version of atomic with this functionality, yet. The -version of atomic command built `in this copr repo `__ contains the functionality to -install standalone container image. +version of atomic command built `in this copr repo +`__ contains the +functionality to install standalone container image. Most of the principles of standalone containers are based on the model & technology of system containers. If you would like to know more about system -containers read `the blog post `__. +containers read `the blog post +`__. diff --git a/source/development/get-involved.rst b/source/development/get-involved.rst index 2103084..57df344 100644 --- a/source/development/get-involved.rst +++ b/source/development/get-involved.rst @@ -13,10 +13,10 @@ following steps for becoming a part of the team. #. Read this wiki page and understand the development methods and technical details. -#. Get in touch with us on the `devel mailing - list `__ - and our IRC channel, - `#fedora-modularity `__. +#. Get in touch with us on the `devel mailing list + `__ + and our IRC channel, `#fedora-modularity + `__. #. Attend one of our `weekly meetings `__ and introduce yourself. @@ -31,8 +31,8 @@ Get in touch ------------ There's no dedicated mailing list yet and everything regarding this -topic should be discussed on the general `Fedora Development -list `__. +topic should be discussed on the general `Fedora Development list +`__. Most of us also hang out on the #fedora-modularity channel on Freenode. Planning @@ -95,7 +95,9 @@ typically start with the *fm-* prefix and are open to all members of the 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. +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 diff --git a/source/development/integration/coding-style-python.rst b/source/development/integration/coding-style-python.rst index f80d85d..00d87c7 100644 --- a/source/development/integration/coding-style-python.rst +++ b/source/development/integration/coding-style-python.rst @@ -39,8 +39,8 @@ straightened out. Adding `docstrings `__ to modules, classes, methods and functions is encouraged. If you use the -`Sphinx -format `__ +`Sphinx format +`__ to describe parameters, return values, etc., even better! Python 2 and 3 @@ -488,15 +488,15 @@ property and therefore the setter method. External links -------------- -- `Python Design and History - FAQ `__ -- `PEP8: Style Guide for Python - Code `__ -- `PEP20: The Zen of - Python `__ -- `PyFormat `__: Using ``%`` and ``.format()`` for - great good! -- `Sphinx Info field - lists `__ - for docstrings +- `Python Design and History + FAQ `__ +- `PEP8: Style Guide for Python + Code `__ +- `PEP20: The Zen of + Python `__ +- `PyFormat `__: Using ``%`` and ``.format()`` for + great good! +- `Sphinx Info field lists + `__ + for docstrings diff --git a/source/development/resources.rst b/source/development/resources.rst index 0b8e7aa..e2c8a93 100644 --- a/source/development/resources.rst +++ b/source/development/resources.rst @@ -21,11 +21,13 @@ Content `Base Runtime `__ - The Base Runtime is a small system used as a base for running modules. -`Modules `__ - -All the modules we are working on are in the following GitHub organization. Modules are defined by modulemd. +`Modules `__ - All the modules we are +working on are in the following GitHub organization. Modules are defined by +modulemd. -`Containers `__ - -All modules can be also delivered as containers. The following GitHub organization contains definitions of all our containers. +`Containers `__ - All modules can be +also delivered as containers. The following GitHub organization contains +definitions of all our containers. Scripts and tooling diff --git a/source/infrastructure/infrastructure.rst b/source/infrastructure/infrastructure.rst index 89ffb09..b338378 100644 --- a/source/infrastructure/infrastructure.rst +++ b/source/infrastructure/infrastructure.rst @@ -1,18 +1,32 @@ Infrastructure ============== -Modularity will be built using the `Factory 2.0, documented on the Fedora wiki `__. +Modularity will be built using the `Factory 2.0, documented on the Fedora +wiki `__. Focus Documents --------------- -The Factory 2.0 team produces a confusing number of documents. The first round was about the Problem Statements we were trying to solve. Let’s retroactively call them Problem Documents. The `Focus Documents `__ focus on some system or some aspect of our solutions that cut across different problems. The content here doesn’t fit cleanly in one problem statement document, which is why we broke it out. +The Factory 2.0 team produces a confusing number of documents. The first +round was about the Problem Statements we were trying to solve. Let’s +retroactively call them Problem Documents. The `Focus Documents +`__ focus on +some system or some aspect of our solutions that cut across different +problems. The content here doesn’t fit cleanly in one problem statement +document, which is why we broke it out. **The most important ones related to Modularity include**: -`Module Build Service (MBS) `__ - A service that orchestrates module builds in the Fedora infrastructure. +`Module Build Service (MBS) +`__ - A +service that orchestrates module builds in the Fedora infrastructure. -`Arbitrary Branching `__ - Support of version branches in dist-git which allows us to maintain multiple versions of packages and modules. +`Arbitrary Branching +`__ - +Support of version branches in dist-git which allows us to maintain multiple +versions of packages and modules. -`Freshmaker `__ - A service that will automatically rebuild artifacts (like module repositories or container images) to make sure that everything is up to date. +`Freshmaker `__ - +A service that will automatically rebuild artifacts (like module repositories +or container images) to make sure that everything is up to date. diff --git a/source/prototype/boltron/content.rst b/source/prototype/boltron/content.rst index e5cb2ee..bdc5306 100644 --- a/source/prototype/boltron/content.rst +++ b/source/prototype/boltron/content.rst @@ -1,7 +1,9 @@ Boltron Content =============== -The following is a list of modules that we have completed. Many of the `modules are also available as containers `__ on dockerhub. +The following is a list of modules that we have completed. Many of the +`modules are also available as containers +`__ on dockerhub. - `base-runtime-f26` - `container-runtime-f26` @@ -29,5 +31,7 @@ The following is a list of modules that we have completed. Many of the `modules - `systemtools-f26` - `varnish-f26` -For more information about individual modules - both completed and in progress - see the `Fedora Modularity: Modules GitHub space `__. +For more information about individual modules - both completed and in +progress - see the `Fedora Modularity: Modules GitHub space +`__. diff --git a/source/prototype/boltron/feedback.rst b/source/prototype/boltron/feedback.rst index 3cf3955..22fe914 100644 --- a/source/prototype/boltron/feedback.rst +++ b/source/prototype/boltron/feedback.rst @@ -4,11 +4,15 @@ Boltron Feedback General Feedback ---------------- -If you just want to give a basic feedback about Modularity, please use the `General Feedback `__ form. +If you just want to give a basic feedback about Modularity, please use the +`General Feedback `__ form. -You can also get in touch on our `#fedora-modularity irc channel `__. +You can also get in touch on our `#fedora-modularity irc channel +`__. User Experience Walkthrough and Feedback ---------------------------------------- -If you want to give us more detailed feedback on Modularity and the user experience, please use the `Walkthrough and UX Feedback `__ form. +If you want to give us more detailed feedback on Modularity and the user +experience, please use the `Walkthrough and UX Feedback +`__ form. diff --git a/source/prototype/boltron/instructions.rst b/source/prototype/boltron/instructions.rst index 01e5c93..167f62c 100644 --- a/source/prototype/boltron/instructions.rst +++ b/source/prototype/boltron/instructions.rst @@ -1,7 +1,8 @@ Boltron Instructions ==================== -Boltron is shipped as a container image. Use the following commands to pull it and run it: +Boltron is shipped as a container image. Use the following commands to pull +it and run it: :: @@ -14,7 +15,9 @@ Now you are ready to try Boltron! Managing modules with DNF ------------------------- -You can find very similar guide on the `Walkthrough and UX Feedback `__ form - and give us feedback on the go. +You can find very similar guide on the `Walkthrough and UX Feedback +`__ form - and give us feedback on +the go. Listing modules ............... @@ -35,7 +38,8 @@ List all installed modules: Installing modules .................. -Modules are identified by name-stream-version. Each module might have one or more install profiles - pre-defined sets of packages to be installed. +Modules are identified by name-stream-version. Each module might have one or +more install profiles - pre-defined sets of packages to be installed. Modules can be installed by one of the following commands. @@ -59,7 +63,10 @@ Specific examples: Updating the system ................... -The system can be updated the same way as a traditional Fedora. The modules will always follow their streams. That means that if you have nodejs 6 (nodejs-f26) installed, it will not get upgraded to nodejs 8 (nodejs-8) even when it is available. +The system can be updated the same way as a traditional Fedora. The modules +will always follow their streams. That means that if you have nodejs 6 +(nodejs-f26) installed, it will not get upgraded to nodejs 8 (nodejs-8) even +when it is available. :: @@ -68,7 +75,8 @@ The system can be updated the same way as a traditional Fedora. The modules will Changing streams ................ -If you want to change a stream of an installed module, run the same command as if you were installing it, specifying the stream you want to change to. +If you want to change a stream of an installed module, run the same command +as if you were installing it, specifying the stream you want to change to. :: diff --git a/source/prototype/boltron/issues.rst b/source/prototype/boltron/issues.rst index 054566c..2237b84 100644 --- a/source/prototype/boltron/issues.rst +++ b/source/prototype/boltron/issues.rst @@ -1,12 +1,16 @@ Known Issues ============ -This page tracks the known issues in the Boltron release. If you find anything that is not here, you can submit it into the issue tracker. +This page tracks the known issues in the Boltron release. If you find +anything that is not here, you can submit it into the issue tracker. Issue tracker ------------- -Apart from the `main modularity issue tracker `__, there are also issue trackers for the individual modules, available in the `Fedora Modularity: Modules GitHub space `__. +Apart from the `main modularity issue tracker +`__, there are also issue trackers for +the individual modules, available in the `Fedora Modularity: Modules GitHub +space `__. You can also use one of the feedback forms: :doc:`/prototype/boltron/feedback`. @@ -16,14 +20,22 @@ List of known Issues DNF doesn't show some modules as installed .......................................... -This is specificaly about the `base-runtime`, `shared-userspace`, and `dnf` modules. The packages from these modules are avilable, but the `dnf module list --installed` won't list them. +This is specificaly about the `base-runtime`, `shared-userspace`, and `dnf` +modules. The packages from these modules are avilable, but the `dnf module +list --installed` won't list them. Microdnf and rpm-ostree don't support modules ................................ -Besides `dnf`, there are two other package managers in Fedora. Both `microdnf` and `rpm-ostree` use `libdnf`, which does not yet support modules. If you're building a container, use the non-minimal image. A future version of Atomic Host's `rpm-ostree` package layering may support modules. +Besides `dnf`, there are two other package managers in Fedora. Both +`microdnf` and `rpm-ostree` use `libdnf`, which does not yet support modules. +If you're building a container, use the non-minimal image. A future version +of Atomic Host's `rpm-ostree` package layering may support modules. Update command is `dnf module update`, not `dnf update` ....................................................... -As Boltron won't get any updates, the update functionality wasn't the biggest priority. Even with this it has been fully implemented client-side in a 'dnf module update' command. The 'dnf update' command will work as expected in F27. +As Boltron won't get any updates, the update functionality wasn't the biggest +priority. Even with this it has been fully implemented client-side in a 'dnf +module update' command. The 'dnf update' command will work as expected in +F27. From d37e53a113bea974e3457862596561834c4d853f Mon Sep 17 00:00:00 2001 From: Nils Philippsen Date: Jul 26 2017 09:25:49 +0000 Subject: [PATCH 2/5] remove trailing whitespace --- diff --git a/build-start.sh b/build-start.sh index 9fdd19f..187e46d 100755 --- a/build-start.sh +++ b/build-start.sh @@ -6,4 +6,3 @@ cd /var/www/html make html mv /var/www/html/build/html/* /var/www/html/ /usr/sbin/httpd -X - diff --git a/source/_themes/modularity/theme.conf b/source/_themes/modularity/theme.conf index 218fc99..d5fd2fc 100644 --- a/source/_themes/modularity/theme.conf +++ b/source/_themes/modularity/theme.conf @@ -4,7 +4,7 @@ stylesheet = css/theme.css [options] typekit_id = hiw1hhg -analytics_id = +analytics_id = sticky_navigation = False logo_only = collapse_navigation = False diff --git a/source/design/building-naming.rst b/source/design/building-naming.rst index 6dec989..f931cc6 100644 --- a/source/design/building-naming.rst +++ b/source/design/building-naming.rst @@ -16,7 +16,7 @@ We use these terms: unit. May depend on other modules. - **Stack.** A complete tree of modules. A stack can be thought of as a top-level module, with the understanding that we’re implicitly - including all of that module’s dependencies in the stack. HOwever, when + including all of that module’s dependencies in the stack. HOwever, when the stack is delivered to the end-user it appears as "just another module." - **Artifact** or **image**. An actual set of bits built out of modules, in a format intended to be distributed or deployed in some @@ -34,7 +34,7 @@ We will also distinguish between: - A **Compose** of a module: a process which assembles pre-compiled packages into an organised module, but which includes no compilation step itself. Sometimes we also use the term **Coallesce** for this scenario - to distinguish between the existing, Fedora term "Compose" which is very + to distinguish between the existing, Fedora term "Compose" which is very similar but not quite the same. .. rubric:: TOC diff --git a/source/design/building-naming/stack.rst b/source/design/building-naming/stack.rst index adec375..5c74673 100644 --- a/source/design/building-naming/stack.rst +++ b/source/design/building-naming/stack.rst @@ -21,8 +21,8 @@ the module plus all its implied dependencies as a single unit, to distinguish that from the individual modules within the stack; the stack content and metadata may have exactly the same format as module metadata (the metadata is the same colour here for a reason!) But it’s still -important (at least internally, probably not for end users) to make the -distinction between a single module, and a module plus all the external +important (at least internally, probably not for end users) to make the +distinction between a single module, and a module plus all the external dependencies it relies on. Importantly, we can take two modules with different lifecycles and diff --git a/source/design/constructing.rst b/source/design/constructing.rst index 9266547..062bcce 100644 --- a/source/design/constructing.rst +++ b/source/design/constructing.rst @@ -36,7 +36,7 @@ justify a **static manifest** to assign packages to modules. Once we have parts of the distribution on different release cycles, we also have the issue of how to maintain different versions branching on different criteria and different schedules. Branching and versioning is -relevant here, but is a complex topic in its own right and is covered under +relevant here, but is a complex topic in its own right and is covered under :doc:`/design/versioning`. .. rubric:: TOC diff --git a/source/design/constructing/compose-distribution.rst b/source/design/constructing/compose-distribution.rst index a106478..b1ed9f5 100644 --- a/source/design/constructing/compose-distribution.rst +++ b/source/design/constructing/compose-distribution.rst @@ -226,7 +226,7 @@ But ultimately, Fedora still wants to be able to produce a planned release spanning many modules, and users still want to have controlled, predictable releases, rather than having modules dribble into a release in drips. We still have major release events such as Fedora major/minor -updates. +updates. So decomposing the release into loosely-coupled compose steps is all well enough, but we need more than just chain rebuilds to bring it all diff --git a/source/design/versioning.rst b/source/design/versioning.rst index 3767d40..ac21bfc 100644 --- a/source/design/versioning.rst +++ b/source/design/versioning.rst @@ -17,7 +17,7 @@ Yet we need to control this complexity: the engineering involved has to be sustainable, and the combinations we offer to the user need to be manageable. This is especially true as different tools represent branches in different ways (eg. bugzilla represents branches as the -“version” field for a product, and also has version-specific flags; +“version” field for a product, and also has version-specific flags; koji has koji tags which act as branches, etc.) This leads to some complex constraints, which we will explore in this diff --git a/source/design/versioning/coherency.rst b/source/design/versioning/coherency.rst index 82ab87e..a55224e 100644 --- a/source/design/versioning/coherency.rst +++ b/source/design/versioning/coherency.rst @@ -12,7 +12,7 @@ places: tools share a common understanding of the various product branches (fXX etc.) and work flows naturally between them. - Users consume products knowing which branch they are on; they - have the option to choose between branches (F25 after F26 has + have the option to choose between branches (F25 after F26 has been released), and they report bugs and review CVEs corresponding to those branches @@ -55,7 +55,7 @@ independently from a single master release cadence. But do we really want all modules to be released without any synchronisation or common branching at all? -History suggests we do not. +History suggests we do not. In the future we likely have many completely-decoupled modules for additional content outside the base Fedora runtime platform. But we may diff --git a/source/design/versioning/constraints.rst b/source/design/versioning/constraints.rst index df554e7..fbc409d 100644 --- a/source/design/versioning/constraints.rst +++ b/source/design/versioning/constraints.rst @@ -14,13 +14,13 @@ policy. Splitting a binary package build over multiple modules ------------------------------------------------------ -This is something that is surprisingly common. +This is something that is surprisingly common. -Examples might be when we want to include a library to support our own +Examples might be when we want to include a library to support our own package/application, but do not want to give it full support for end-users; we -might include the library itself, but not include the components +might include the library itself, but not include the components that provide the ability to develop against it (the include files, static -libraries etc. that typically land in a -devel binary rpm). +libraries etc. that typically land in a -devel binary rpm). Can we do this naturally in a modular build chain? Clearly it breaks any assumption that a module can be both compiled and composed in complete diff --git a/source/design/versioning/managing.rst b/source/design/versioning/managing.rst index 705a349..17806d4 100644 --- a/source/design/versioning/managing.rst +++ b/source/design/versioning/managing.rst @@ -82,9 +82,9 @@ Converging branches ~~~~~~~~~~~~~~~~~~~ Just as important as forking a new branch is converging existing -branches. In an f-stream model, a new feature scheduled for the next release -is made available in a prior release. The f-stream is the early-access branch; -the intent is that when the next release occurs, it introduces that +branches. In an f-stream model, a new feature scheduled for the next release +is made available in a prior release. The f-stream is the early-access branch; +the intent is that when the next release occurs, it introduces that feature into the mainline stream, and the f-stream is no longer needed: any component depending on that feature moves back off the f-stream branch and onto the mainline. diff --git a/source/design/versioning/properties.rst b/source/design/versioning/properties.rst index 1257658..78985dc 100644 --- a/source/design/versioning/properties.rst +++ b/source/design/versioning/properties.rst @@ -68,7 +68,7 @@ automatically update it to 2.4. Any dependencies brought in by either must also prevent such interference. And yet if a certain package *does* support parallel installation of -different version branches at the same time +different version branches at the same time (eg. software collection-based packages), then the separate installed versions at any time must each be updatable by their own specific update stream. diff --git a/source/design/versioning/terminology.rst b/source/design/versioning/terminology.rst index 56b6734..1e6b142 100644 --- a/source/design/versioning/terminology.rst +++ b/source/design/versioning/terminology.rst @@ -16,7 +16,7 @@ straight, we need to distinguish between: A version branch **may** correspond to a new **major version** of the module, but there may be exceptions: for example, when we add specific features as a side-branch of an existing major version. The - new branch may differ by SLA (eg. a faster moving Python) or by + new branch may differ by SLA (eg. a faster moving Python) or by feature (eg. an “f-stream” branch giving early access to a specific new feature planned to be released in a subsequent update). diff --git a/source/development/building-modules/containers-local.rst b/source/development/building-modules/containers-local.rst index f6efcd5..abcc368 100644 --- a/source/development/building-modules/containers-local.rst +++ b/source/development/building-modules/containers-local.rst @@ -3,7 +3,7 @@ Building containers locally When you have your module built, let's put it in a container, so we can use it. As an example, we will use the `perl image -`__. +`__. Module RPM repository --------------------- diff --git a/source/development/resources.rst b/source/development/resources.rst index e2c8a93..8583575 100644 --- a/source/development/resources.rst +++ b/source/development/resources.rst @@ -10,7 +10,7 @@ Git Repositories Specifications ~~~~~~~~~~~~~~ -`Modulemd `__ - +`Modulemd `__ - This repository contains the definition of metadata format (Modulemd) used to describe every module. It also contains Python library used to manipulate files in this format. diff --git a/source/prototype/boltron/instructions.rst b/source/prototype/boltron/instructions.rst index 167f62c..90c940d 100644 --- a/source/prototype/boltron/instructions.rst +++ b/source/prototype/boltron/instructions.rst @@ -39,7 +39,7 @@ Installing modules .................. Modules are identified by name-stream-version. Each module might have one or -more install profiles - pre-defined sets of packages to be installed. +more install profiles - pre-defined sets of packages to be installed. Modules can be installed by one of the following commands. From 4de00851529754e0dad1cbc0d3f0e66f8f431275 Mon Sep 17 00:00:00 2001 From: Nils Philippsen Date: Jul 26 2017 09:32:12 +0000 Subject: [PATCH 3/5] fix typo --- diff --git a/source/design/building-naming.rst b/source/design/building-naming.rst index f931cc6..b478382 100644 --- a/source/design/building-naming.rst +++ b/source/design/building-naming.rst @@ -16,7 +16,7 @@ We use these terms: unit. May depend on other modules. - **Stack.** A complete tree of modules. A stack can be thought of as a top-level module, with the understanding that we’re implicitly - including all of that module’s dependencies in the stack. HOwever, when + including all of that module’s dependencies in the stack. However, when the stack is delivered to the end-user it appears as "just another module." - **Artifact** or **image**. An actual set of bits built out of modules, in a format intended to be distributed or deployed in some From 52e342230ee2022655d406815d72d60b73514a1a Mon Sep 17 00:00:00 2001 From: Nils Philippsen Date: Jul 26 2017 09:34:37 +0000 Subject: [PATCH 4/5] fix too short underlines --- diff --git a/source/prototype/boltron/issues.rst b/source/prototype/boltron/issues.rst index 2237b84..1a0c780 100644 --- a/source/prototype/boltron/issues.rst +++ b/source/prototype/boltron/issues.rst @@ -15,7 +15,7 @@ space `__. You can also use one of the feedback forms: :doc:`/prototype/boltron/feedback`. List of known Issues --------------- +-------------------- DNF doesn't show some modules as installed .......................................... @@ -25,7 +25,7 @@ modules. The packages from these modules are avilable, but the `dnf module list --installed` won't list them. Microdnf and rpm-ostree don't support modules -................................ +............................................. Besides `dnf`, there are two other package managers in Fedora. Both `microdnf` and `rpm-ostree` use `libdnf`, which does not yet support modules. From f4b27a65ef1bdbdce8eb0037e231bb5b324d2c88 Mon Sep 17 00:00:00 2001 From: Nils Philippsen Date: Jul 26 2017 09:34:37 +0000 Subject: [PATCH 5/5] be more explicit about listing dependencies see https://pagure.io/modulemd/issue/43 for details --- diff --git a/source/development/building-modules/developing.rst b/source/development/building-modules/developing.rst index f08b6af..dee8d91 100644 --- a/source/development/building-modules/developing.rst +++ b/source/development/building-modules/developing.rst @@ -3,9 +3,9 @@ Defining modules in modulemd To have your module build, you need to start with writing a `modulemd `__ file which is a definition of your module -including the components, API, and all the information necessary to build your -module like specifying the build root and a build order for the packages. -Let’s have a look at an example Vim module: +including the components, API, and all the information necessary to build +your module like specifying build dependencies and a build order for the +packages. Let’s have a look at an example Vim module: :: diff --git a/source/development/building-modules/module-guidelines.rst b/source/development/building-modules/module-guidelines.rst index 0562804..f5a114d 100644 --- a/source/development/building-modules/module-guidelines.rst +++ b/source/development/building-modules/module-guidelines.rst @@ -288,7 +288,10 @@ RPM content Module RPM content is defined in the ``rpms`` subsection of ``components`` and typically consists of one or more packages described by their SRPM names and additional extra key-value pairs, some required -and some optional, associated with them. +and some optional, associated with them. The packages listed contain everything +that makes up the API of the module, as well as any build and runtime +dependencies of them that aren't satisfied by modules listed as +``buildrequires`` or ``requires`` in the ``dependencies`` section. :: @@ -306,7 +309,7 @@ and some optional, associated with them. multilib: - x86_64 dependency-of-foo: - rationale: Needed for foo. + rationale: Needed for building foo. buildorder: 50 repository: git://git.example.com/dependency-of-foo.git ref: master @@ -430,6 +433,32 @@ optional metadata. foo: rationale: An example RPM component. +Minimal module with RPM content and build dependency +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Yet another flavour of the minimal module, containing one RPM package +with SRPM name ``foo`` and another with SRPM name ``bar`` which is required for building and running ``foo``. This module doesn't define any dependencies on other modules or optional metadata. + +:: + + document: modulemd + version: 1 + data: + summary: An example summary + description: And an example description. + license: + module: + - MIT + components: + rpms: + foo: + rationale: An example RPM component. + buildorder: 2 + bar: + rationale: > + An example build and runtime dependency of foo. + buildorder: 1 + Minimal module with RPM content but with the -docs subpackage excluded ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -549,11 +578,15 @@ included components and populate the ``data`` → ``license`` → ``content`` li rpms: common-package: rationale: The key component of this module. + buildorder: 2 ref: common-release-branch common-plugins: rationale: Extensions for common-package. - buildorder: 1 + buildorder: 3 ref: common-release-branch + common-builddep: + rationale: A build dependency of common-package. + buildorder: 1 Complete module definition ~~~~~~~~~~~~~~~~~~~~~~~~~~