From 4440588a9e1c3299ee1ce78d02d71eaeab736bd6 Mon Sep 17 00:00:00 2001 From: Adam Samalik Date: Mar 02 2018 17:38:25 +0000 Subject: [PATCH 1/9] add some content to building modules --- diff --git a/_topic_map.yml b/_topic_map.yml index b25fd29..938dfab 100644 --- a/_topic_map.yml +++ b/_topic_map.yml @@ -51,3 +51,4 @@ Topics: File: References - Name: FAQ File: FAQ + \ No newline at end of file diff --git a/en-US/Making_Modules.adoc b/en-US/Making_Modules.adoc index b0bf635..24459df 100644 --- a/en-US/Making_Modules.adoc +++ b/en-US/Making_Modules.adoc @@ -2,6 +2,142 @@ NOTE: This page is a placeholder. You can make this page more useful by submitting a pull-request to https://pagure.io/fedora-docs/modularity/ +== Understanding the build process + +=== Traditional builds + +image::modularity-building-trad.png[,70%,] + +Traditionaly, each package would have multiple branches, one for every release. Such scheme is very straighforward, but limits us in two ways: + +1. Only one version of a package can be built for each release +2. Even when there is the same version for multiple releases, packagers need to maintain multiple branches + +=== Modular builds + +image::modularity-building-modules.png[,90%,] + +Modularity introduces some new features to the build pipeline: + +Stream branching:: + Instead of branching per release, packages are branched per major version. This reduces the source duplication and the number of branches packagers need to maintain. + +Stream expansion:: + An ability to build one source branch for multiple releases. + +Modules:: + Modules are the mechanism of delivering additional versions of packages to Fedora. They have independent lifecycles and are usualy built for all supported Fedora releases. + +Thanks to these features, it becomes possible to build multiple versions of packages for all releases while maintaining lower number of branches. + + +== Creating a new module + +If you wish to package an *alternative version* of something, or if you wish to maintain your *packages on an independent lifecycle* to the Fedora release, modules are the way to go. + +=== Designing a new module + +In general, *modules* represent an application, a language stack, a logical group of tools, or even a single package. An example could be httpd, PostgreSQL, developer tools, etc. + +Modules have one or more *streams*. Streams are very similar to a major version of an application, i.e. Nodejs 6 vs. Nodejs 8, but also "latest" or "devel". Streams have *independent lifecycles*. + +In technical terms, modules can *replace or provide additional packages* to the traditional Fedora releases. + +When making a new module, think of the major three things: + +1. a *name* that would represent it well i.e. nodejs, postgresql, django. +2. a *stream name* that would best describe its lifecycle and compatibility goal i.e. a major version, latest, devel, etc. We expect that using a major version will be the most common stream name. +3. a *list of packages* the module will provide. + +There are other aspects of modules, but these three are the most important ones. + +=== Requesting dist-git repositories + +TODO + +=== Defining the module + +Modules are defined using a https://pagure.io/modulemd[modulemd file]. A minimal example: + +WARNING: The following example is modulemd version 1 that doesn't support stream expansion. We are introducing a new version very soon. + +modulemd.yaml +[source,yaml] +---- +document: modulemd +version: 1 +data: + summary: An example module <1> + description: >- + A module for the demonstration <2> + of the metadata format. + license: + module: + - MIT <3> + dependencies: <4> + buildrequires: + platform: f27 + requires: + platform: f27 + references: <5> + community: http://www.example.com/ + documentation: http://www.example.com/ + tracker: http://www.example.com/ + profiles: <6> + default: + rpms: + - foo + - foo-extras + minimal: + description: Minimal profile. + rpms: + - foo + api: <7> + rpms: + - foo + components: <8> + rpms: + foo: <9> + rationale: Our main package. <10> + ref: 2.4 <11> + bar: + rationale: Some another package. + ref: latest +---- + +<1> A short summary describing the module. + +<2> A longer summary describing the module. + +<3> Licence of this modulemd file. + +<4> Other modules and their streams that are used as runtime and build dependencies. "platform" is a reserved word for the Fedora releases. The stream names follow the usual short names for the releases i.e. "f26", "f27", "epel7", etc. In this version of modulemd (v1) there is no support for stream expansion. That means that only one release can be selected. However, in the upcoming version of modulemd (v2) there will be an option to list multiple ones. + +<5> Various references to the upstream. + +<6> Installation profiles that will help users to install the module. Keep in mind that not all the packages from the module need to be installed. + +<7> The module's public RPM-level API. A list of binary RPM names that are considered to be the main and stable feature of the module + +<8> List of packages that are part of this module. + +<9> Name of a package. + +<10> A rationale why the package has been included. This is only for humans. + +<11> A dist-git branch of the package. + +== Building for the first time and adding it to Fedora + +TBD + +== Building and updating modules + +TBD + + + + == Overview of module files explain module.yaml, what it should be named, what the branch should be called, where to find the spec, some example diff --git a/en-US/images/modularity-building-modules.png b/en-US/images/modularity-building-modules.png new file mode 100644 index 0000000..ae6dbcd Binary files /dev/null and b/en-US/images/modularity-building-modules.png differ diff --git a/en-US/images/modularity-building-trad.png b/en-US/images/modularity-building-trad.png new file mode 100644 index 0000000..5e5e89f Binary files /dev/null and b/en-US/images/modularity-building-trad.png differ From 2ff0a91a7ea6c4aaf6eb4bb0da776b113f96eb6c Mon Sep 17 00:00:00 2001 From: Adam Samalik Date: Mar 02 2018 17:40:40 +0000 Subject: [PATCH 2/9] one sentence per line --- diff --git a/en-US/Making_Modules.adoc b/en-US/Making_Modules.adoc index 24459df..840078c 100644 --- a/en-US/Making_Modules.adoc +++ b/en-US/Making_Modules.adoc @@ -8,7 +8,8 @@ NOTE: This page is a placeholder. You can make this page more useful by submitti image::modularity-building-trad.png[,70%,] -Traditionaly, each package would have multiple branches, one for every release. Such scheme is very straighforward, but limits us in two ways: +Traditionaly, each package would have multiple branches, one for every release. +Such scheme is very straighforward, but limits us in two ways: 1. Only one version of a package can be built for each release 2. Even when there is the same version for multiple releases, packagers need to maintain multiple branches @@ -20,13 +21,15 @@ image::modularity-building-modules.png[,90%,] Modularity introduces some new features to the build pipeline: Stream branching:: - Instead of branching per release, packages are branched per major version. This reduces the source duplication and the number of branches packagers need to maintain. + Instead of branching per release, packages are branched per major version. + This reduces the source duplication and the number of branches packagers need to maintain. Stream expansion:: An ability to build one source branch for multiple releases. Modules:: - Modules are the mechanism of delivering additional versions of packages to Fedora. They have independent lifecycles and are usualy built for all supported Fedora releases. + Modules are the mechanism of delivering additional versions of packages to Fedora. + They have independent lifecycles and are usualy built for all supported Fedora releases. Thanks to these features, it becomes possible to build multiple versions of packages for all releases while maintaining lower number of branches. @@ -37,9 +40,11 @@ If you wish to package an *alternative version* of something, or if you wish to === Designing a new module -In general, *modules* represent an application, a language stack, a logical group of tools, or even a single package. An example could be httpd, PostgreSQL, developer tools, etc. +In general, *modules* represent an application, a language stack, a logical group of tools, or even a single package. +An example could be httpd, PostgreSQL, developer tools, etc. -Modules have one or more *streams*. Streams are very similar to a major version of an application, i.e. Nodejs 6 vs. Nodejs 8, but also "latest" or "devel". Streams have *independent lifecycles*. +Modules have one or more *streams*. Streams are very similar to a major version of an application, i.e. Nodejs 6 vs. Nodejs 8, but also "latest" or "devel". +Streams have *independent lifecycles*. In technical terms, modules can *replace or provide additional packages* to the traditional Fedora releases. @@ -111,19 +116,27 @@ data: <3> Licence of this modulemd file. -<4> Other modules and their streams that are used as runtime and build dependencies. "platform" is a reserved word for the Fedora releases. The stream names follow the usual short names for the releases i.e. "f26", "f27", "epel7", etc. In this version of modulemd (v1) there is no support for stream expansion. That means that only one release can be selected. However, in the upcoming version of modulemd (v2) there will be an option to list multiple ones. +<4> Other modules and their streams that are used as runtime and build dependencies. +"platform" is a reserved word for the Fedora releases. +The stream names follow the usual short names for the releases i.e. "f26", "f27", "epel7", etc. +In this version of modulemd (v1) there is no support for stream expansion. +That means that only one release can be selected. +However, in the upcoming version of modulemd (v2) there will be an option to list multiple ones. <5> Various references to the upstream. -<6> Installation profiles that will help users to install the module. Keep in mind that not all the packages from the module need to be installed. +<6> Installation profiles that will help users to install the module. +Keep in mind that not all the packages from the module need to be installed. -<7> The module's public RPM-level API. A list of binary RPM names that are considered to be the main and stable feature of the module +<7> The module's public RPM-level API. +A list of binary RPM names that are considered to be the main and stable feature of the module <8> List of packages that are part of this module. <9> Name of a package. -<10> A rationale why the package has been included. This is only for humans. +<10> A rationale why the package has been included. +This is only for humans. <11> A dist-git branch of the package. From fd4711a9f463d36832e9733f0348fa5b8fc164b9 Mon Sep 17 00:00:00 2001 From: Adam Samalik Date: Mar 12 2018 17:53:05 +0000 Subject: [PATCH 3/9] making modules - structure and some initial content --- diff --git a/_topic_map.yml b/_topic_map.yml index 938dfab..58a7086 100644 --- a/_topic_map.yml +++ b/_topic_map.yml @@ -24,15 +24,29 @@ Name: Fedora Modularity Dir: en-US Topics: -# - Name: index alias -# File: index -# Alias: en-US/brian - Name: What is Modularity File: index - Name: Using Modules in Fedora File: Using_Modules - Name: Making Modules - File: Making_Modules + Dir: making-modules + Topics: + - Name: WHY (benefits) + File: why + - Name: HOW (understanding) + File: how + - Name: --> Understanding modules + File: understanding + - Name: --> Storing source + File: source + - Name: --> Defining modules + File: defining + - Name: --> Building and installing + File: facts + - Name: WHAT (guides) + File: what + - Name: --> Requesting dist-git branches + File: requesting_branches - Name: Architecture Dir: architecture Topics: @@ -47,6 +61,8 @@ Topics: Topics: - Name: Communication File: Communication + - Name: Working Groups & Teams + File: working_groups_and_teams - Name: References File: References - Name: FAQ diff --git a/en-US/community/working_groups_and_teams.adoc b/en-US/community/working_groups_and_teams.adoc new file mode 100644 index 0000000..d3f6a1e --- /dev/null +++ b/en-US/community/working_groups_and_teams.adoc @@ -0,0 +1,9 @@ += Working Groups and Teams + +Modularity is driven by the https://fedoraproject.org/wiki/Modularity_Working_Group[Modularity Working Group] + +However, Modularity couldn't happen without other working groups contributing a significant portion of effort into it, i.e.: + +* https://fedoraproject.org/wiki/Server[Server Working Group] +* https://docs.pagure.org/releng/[Fedora Release Engineering] +* https://fedoraproject.org/wiki/Infrastructure[Fedora Infrastructure] \ No newline at end of file diff --git a/en-US/making-modules/defining.adoc b/en-US/making-modules/defining.adoc new file mode 100644 index 0000000..e8f2f88 --- /dev/null +++ b/en-US/making-modules/defining.adoc @@ -0,0 +1,79 @@ += Defining modules using modulemd + +Modules are defined using a https://pagure.io/modulemd[modulemd file]. A minimal example: + +WARNING: The following example is modulemd version 1 that doesn't support stream expansion. We are introducing a new version very soon. + +modulemd.yaml +[source,yaml] +---- +document: modulemd +version: 1 +data: + summary: An example module <1> + description: >- + A module for the demonstration <2> + of the metadata format. + license: + module: + - MIT <3> + dependencies: <4> + buildrequires: + platform: f27 + requires: + platform: f27 + references: <5> + community: http://www.example.com/ + documentation: http://www.example.com/ + tracker: http://www.example.com/ + profiles: <6> + default: + rpms: + - foo + - foo-extras + minimal: + description: Minimal profile. + rpms: + - foo + api: <7> + rpms: + - foo + components: <8> + rpms: + foo: <9> + rationale: Our main package. <10> + ref: 2.4 <11> + bar: + rationale: Some another package. + ref: latest +---- + +<1> A short summary describing the module. + +<2> A longer summary describing the module. + +<3> Licence of this modulemd file. + +<4> Other modules and their streams that are used as runtime and build dependencies. +"platform" is a reserved word for the Fedora releases. +The stream names follow the usual short names for the releases i.e. "f26", "f27", "epel7", etc. +In this version of modulemd (v1) there is no support for stream expansion. +That means that only one release can be selected. +However, in the upcoming version of modulemd (v2) there will be an option to list multiple ones. + +<5> Various references to the upstream. + +<6> Installation profiles that will help users to install the module. +Keep in mind that not all the packages from the module need to be installed. + +<7> The module's public RPM-level API. +A list of binary RPM names that are considered to be the main and stable feature of the module + +<8> List of packages that are part of this module. + +<9> Name of a package. + +<10> A rationale why the package has been included. +This is only for humans. + +<11> A dist-git branch of the package. \ No newline at end of file diff --git a/en-US/making-modules/facts.adoc b/en-US/making-modules/facts.adoc new file mode 100644 index 0000000..e69de29 --- /dev/null +++ b/en-US/making-modules/facts.adoc diff --git a/en-US/making-modules/how.adoc b/en-US/making-modules/how.adoc new file mode 100644 index 0000000..77c0789 --- /dev/null +++ b/en-US/making-modules/how.adoc @@ -0,0 +1,72 @@ += How to make a module + +If you have decided you want to make a module: + +. Understand what modules are and how they are organized. +. Learn about how Fedora stores module sources in dist-git. +. Learn about the module definition file — modulemd. +. Learn about how modules are built and installed. + + + + + + + + + + +== Modules are identified by + +* Name +* Stream +* Version +* Context +* Architecture + +== Module source consists of + +* RPM sources (in dist-git) +* Module definition (in dist-git) + +== Storing and organizing sources + +=== Trad branches -> Trad release + +* only for RPM sources +* RPM branch name defines where the binary goes + +=== Stream branches -> Module streams + +* for RPM sources and module definitions +* module streams list their RPM components (the other way round compared to a trad release) + +== Understanding the module definition (modulemd) + +* summary and description +* list of components (srpm name + branch) +* "build" information +** build groups +** filter +** macros +** dependencies +* "use" information +** installation profiles +** licenses +** refs to community, docs, bug tracker +** API + +== How module interacts with the base and other modules + +=== Runtime + +* can use packages from the base as dependencies +* can use other module streams as dependencies +* can override/replace other packages in base + +=== Build + +* can use packages from the base as build dependencies +* can use other module streams as build dependencies +* can expand across multiple modules or bases (one source produces several binaries, Stream Expansion) + diff --git a/en-US/making-modules/requesting_branches.adoc b/en-US/making-modules/requesting_branches.adoc new file mode 100644 index 0000000..e69de29 --- /dev/null +++ b/en-US/making-modules/requesting_branches.adoc diff --git a/en-US/making-modules/source.adoc b/en-US/making-modules/source.adoc new file mode 100644 index 0000000..c88af2c --- /dev/null +++ b/en-US/making-modules/source.adoc @@ -0,0 +1,29 @@ += Storing module sources + +Module sources consist of two main parts: + +. RPM package sources +. module definition file + +Both of these are stored in https://src.fedoraproject.org/[Fedora dist-git]. Dist-git is organized into repositories, each having multiple branches. + +== Stream branching + +Modularity introduced https://fedoraproject.org/wiki/Changes/ArbitraryBranching[Stream Branching] (formerly Arbitrary Branching) that is used for both module definitions and RPM packages that are part of modules. + +=== Modules + +Module definitions are stored in the `/modules` namespace and only consist of a modulemd file that defines the module itself. + +Each module has a repository with branches corresponding to different streams. The repository and branch naming map to the module ID: + +* Repository name -> module name +* Branch name -> stream name +* Commit timestamp -> module version + +=== Packages + +RPM Packages are stored in the `/rpms` namespace, and are also organized into stream branches. However, only the repository name map to the name of the package: + +* Repository name -> package name +* Branch name doesn't map to anything, but is used as a reference in the module definition. \ No newline at end of file diff --git a/en-US/making-modules/understanding.adoc b/en-US/making-modules/understanding.adoc new file mode 100644 index 0000000..bee6689 --- /dev/null +++ b/en-US/making-modules/understanding.adoc @@ -0,0 +1,59 @@ += Understanding modules + +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. + +Modules are made available in multiple streams (see below) and have independent lifecycles from the base distribution. + + +== Identifying and organizing modules + +Modules are uniquely identified by five properties: _name_, _stream_, _version_, _context_, and _architecture_. + +=== Source level ID + +At the source level, modules are only identified by the first three: _name_, _stream_, and _version_. + +==== Name + +Name of the module corresponds to the name of the application or the language stack it represents. + +An example of a name could be _postgresql_ for a PostgreSQL database module, or _nodejs_ for a Node.js runtime. + +==== Stream + +Streams are variants of a module with a certain promise. + +In most cases, streams promise *backwards compatibility* with a major version of the application or the language stack they provide. For example, let's say the Node.js runtime is supported in two major versions: 6 and 8. In this case, the module _nodejs_ would have two streams: _6_ and _8_. + +However, streams can also promise different things such as *stability*. A good example of this is the _calc_ package in Fedora which is maintained in two upstream branches: _stable_ for the latest stable release and _unstable_ for the latest development version. Using modularity, this package could be built as a _calc_ module in two different streams: _stable_ and _unstable_. + +In addition to the version promise, streams are also a way for packagers to communicate the *level of maintennance*. Does the maintainer plan to apply every minor patch? Will they apply security fixes quickly? Or is the module updated only twice a year? This can also be part of the promise. + +Other different example could be a stream that provides the software compiled using some experimental flags increasing the performance. + +Anyway, you get the idea. Streams are very flexible and powerful tool. Use them wisely. + +==== Version + +Versions are just updates of a given stream. Technically, version is a number generated by the build system. Higher number always wins. + +=== Binary level ID + +Building a module from one source can result in multiple different binaries. Different binaries are typically produced for different architectures (i.e. _x86_64_, _armv7hl_, etc.) and different Fedora releases (i.e. Fedora 28, Fedora 29, EPEL 7, etc.). + +In addition to the _name_, _stream_, and _version_ fields described above, there are two more for binaries: + +==== Architecture + +https://fedoraproject.org/wiki/Architectures[ Fedora is built for many different architectures]. The architecture field simply distinguishes architecture-specific binaries from each other. + +The value is typically the same as with RPM packages, i.e. _x86_64_, _armv7hl_, etc. + +==== Context + +Context is used to distinguish binaries built for different Fedora releases. Thanks to https://fedoraproject.org/wiki/Infrastructure/Factory2/Focus/StreamExpansion[stream expansion], modules can also be built against multiple streams of other modules, i.e. different versions of a language runtime etc. + +The value is generated by the build system and is usually hidden from the user as it doesn't have any informational value by itself — it is a hash. However, the client tooling consuming this valie can present it in a useful way. + +One way of representing the context could be listing the Fedora releases for which a certain module has been built. + diff --git a/en-US/making-modules/what.adoc b/en-US/making-modules/what.adoc new file mode 100644 index 0000000..e3b957b --- /dev/null +++ b/en-US/making-modules/what.adoc @@ -0,0 +1,7 @@ += What to do to make modules + +This section contains end-to-end guides to solve a particular user story such as: + +* Requesting new dist-git stream branches for modules and packages +* Building a module for the first time +* Submitting a module update \ No newline at end of file diff --git a/en-US/making-modules/why.adoc b/en-US/making-modules/why.adoc new file mode 100644 index 0000000..8ca30ee --- /dev/null +++ b/en-US/making-modules/why.adoc @@ -0,0 +1,11 @@ += Why to make a module + +Main reasons: + +* additional version +* lifecycle independent from the core / base OS + +Other reasons: + +* help users with installing a multipackage "thing" +* maintaining one source for multiple Fedora releases \ No newline at end of file From fac10750b612f362f243fde1880023d28fd24626 Mon Sep 17 00:00:00 2001 From: Adam Samalik Date: Mar 12 2018 18:02:51 +0000 Subject: [PATCH 4/9] more content --- diff --git a/en-US/making-modules/defining.adoc b/en-US/making-modules/defining.adoc index e8f2f88..f4a694f 100644 --- a/en-US/making-modules/defining.adoc +++ b/en-US/making-modules/defining.adoc @@ -1,6 +1,21 @@ = Defining modules using modulemd -Modules are defined using a https://pagure.io/modulemd[modulemd file]. A minimal example: +Modules are defined using a https://pagure.io/modulemd[modulemd file]. It defines the following information: + +* summary and description +* list of components (srpm name + branch) +* "build" information +** build groups +** filter +** macros +** dependencies +* "use" information +** installation profiles +** licenses +** refs to community, docs, bug tracker +** API + +A minimal example: WARNING: The following example is modulemd version 1 that doesn't support stream expansion. We are introducing a new version very soon. diff --git a/en-US/making-modules/facts.adoc b/en-US/making-modules/facts.adoc index e69de29..894d026 100644 --- a/en-US/making-modules/facts.adoc +++ b/en-US/making-modules/facts.adoc @@ -0,0 +1,15 @@ += Building and installing modules + +== How module interacts with the base and other modules + +=== Runtime + +* can use packages from the base as dependencies +* can use other module streams as dependencies +* can override/replace other packages in base + +=== Build + +* can use packages from the base as build dependencies +* can use other module streams as build dependencies +* can expand across multiple modules or bases (one source produces several binaries, Stream Expansion) \ No newline at end of file diff --git a/en-US/making-modules/how.adoc b/en-US/making-modules/how.adoc index 77c0789..5ac6996 100644 --- a/en-US/making-modules/how.adoc +++ b/en-US/making-modules/how.adoc @@ -5,68 +5,5 @@ If you have decided you want to make a module: . Understand what modules are and how they are organized. . Learn about how Fedora stores module sources in dist-git. . Learn about the module definition file — modulemd. -. Learn about how modules are built and installed. - - - - - - - - - - -== Modules are identified by - -* Name -* Stream -* Version -* Context -* Architecture - -== Module source consists of - -* RPM sources (in dist-git) -* Module definition (in dist-git) - -== Storing and organizing sources - -=== Trad branches -> Trad release - -* only for RPM sources -* RPM branch name defines where the binary goes - -=== Stream branches -> Module streams - -* for RPM sources and module definitions -* module streams list their RPM components (the other way round compared to a trad release) - -== Understanding the module definition (modulemd) - -* summary and description -* list of components (srpm name + branch) -* "build" information -** build groups -** filter -** macros -** dependencies -* "use" information -** installation profiles -** licenses -** refs to community, docs, bug tracker -** API - -== How module interacts with the base and other modules - -=== Runtime - -* can use packages from the base as dependencies -* can use other module streams as dependencies -* can override/replace other packages in base - -=== Build - -* can use packages from the base as build dependencies -* can use other module streams as build dependencies -* can expand across multiple modules or bases (one source produces several binaries, Stream Expansion) - +. Learn about how modules are built and installed. +. See the WHAT (guides) section for specific end-to-end guides. \ No newline at end of file From a942659e3c266e70948f7cfc716fb23abb55d5e1 Mon Sep 17 00:00:00 2001 From: Adam Samalik Date: Mar 12 2018 18:09:42 +0000 Subject: [PATCH 5/9] making modules / what - initial structure --- diff --git a/_topic_map.yml b/_topic_map.yml index 58a7086..1de51c4 100644 --- a/_topic_map.yml +++ b/_topic_map.yml @@ -47,6 +47,16 @@ Topics: File: what - Name: --> Requesting dist-git branches File: requesting_branches + - Name: --> Writing and validating modulemd + File: writing_and_validating_modulemd + - Name: --> Building modules locally + File: local_builds + - Name: --> Submitting builds + File: submitting_builds + - Name: --> Adding modules to Fedora + File: adding_modules_to_fedora + - Name: --> Updating modules + File: module_updates - Name: Architecture Dir: architecture Topics: diff --git a/en-US/making-modules/adding_modules_to_fedora.adoc b/en-US/making-modules/adding_modules_to_fedora.adoc new file mode 100644 index 0000000..0df26fe --- /dev/null +++ b/en-US/making-modules/adding_modules_to_fedora.adoc @@ -0,0 +1 @@ += Adding a module to Fedora \ No newline at end of file diff --git a/en-US/making-modules/local_builds.adoc b/en-US/making-modules/local_builds.adoc new file mode 100644 index 0000000..6b85ad5 --- /dev/null +++ b/en-US/making-modules/local_builds.adoc @@ -0,0 +1,3 @@ += Building modules locally + +TBD \ No newline at end of file diff --git a/en-US/making-modules/module_updates.adoc b/en-US/making-modules/module_updates.adoc new file mode 100644 index 0000000..71b7b9b --- /dev/null +++ b/en-US/making-modules/module_updates.adoc @@ -0,0 +1,3 @@ += Updating modules using Bodhi + +TBD \ No newline at end of file diff --git a/en-US/making-modules/requesting_branches.adoc b/en-US/making-modules/requesting_branches.adoc index e69de29..8b37cf7 100644 --- a/en-US/making-modules/requesting_branches.adoc +++ b/en-US/making-modules/requesting_branches.adoc @@ -0,0 +1,3 @@ += Requesting dist-git branches + +TBD \ No newline at end of file diff --git a/en-US/making-modules/submitting_builds.adoc b/en-US/making-modules/submitting_builds.adoc new file mode 100644 index 0000000..6f2c693 --- /dev/null +++ b/en-US/making-modules/submitting_builds.adoc @@ -0,0 +1,3 @@ += Submitting module builds + +TBD \ No newline at end of file diff --git a/en-US/making-modules/writing_and_validating_modulemd.adoc b/en-US/making-modules/writing_and_validating_modulemd.adoc new file mode 100644 index 0000000..47053e3 --- /dev/null +++ b/en-US/making-modules/writing_and_validating_modulemd.adoc @@ -0,0 +1,3 @@ += Writing and validating modulemd + +TBD \ No newline at end of file From 8eb9682696ceb9d6a9b2d8638d737a85ac53d892 Mon Sep 17 00:00:00 2001 From: Adam Samalik Date: Mar 13 2018 14:20:51 +0000 Subject: [PATCH 6/9] reshufle the content --- diff --git a/_topic_map.yml b/_topic_map.yml index 1de51c4..8a913a8 100644 --- a/_topic_map.yml +++ b/_topic_map.yml @@ -26,38 +26,7 @@ Dir: en-US Topics: - Name: What is Modularity File: index - - Name: Using Modules in Fedora - File: Using_Modules - - Name: Making Modules - Dir: making-modules - Topics: - - Name: WHY (benefits) - File: why - - Name: HOW (understanding) - File: how - - Name: --> Understanding modules - File: understanding - - Name: --> Storing source - File: source - - Name: --> Defining modules - File: defining - - Name: --> Building and installing - File: facts - - Name: WHAT (guides) - File: what - - Name: --> Requesting dist-git branches - File: requesting_branches - - Name: --> Writing and validating modulemd - File: writing_and_validating_modulemd - - Name: --> Building modules locally - File: local_builds - - Name: --> Submitting builds - File: submitting_builds - - Name: --> Adding modules to Fedora - File: adding_modules_to_fedora - - Name: --> Updating modules - File: module_updates - - Name: Architecture + - Name: How does it work Dir: architecture Topics: - Name: Main Concepts @@ -66,6 +35,30 @@ Topics: File: Building_Software - Name: Consuming Software File: Consuming_Software + - Name: Using Modules in Fedora + File: Using_Modules + - Name: Making Modules + Dir: making-modules + Topics: + - Name: Naming and organizing modules + File: Naming_and_organizing_modules + - Name: Storing and defining sources + File: Storing_and_defining_sources + - Name: Building and installing + File: Building_and_installing + - Name: Requesting repositories + File: Requesting_repositories + - Name: Creating sources + File: Creating_sources + - Name: Building modules locally + File: Building_modules_locally + - Name: Submitting builds + File: Submitting_builds + - Name: Adding modules to Fedora + File: Adding_modules_to_fedora + - Name: Updating modules + File: Updating_modules + - Name: Community Dir: community Topics: diff --git a/en-US/Making_Modules.adoc b/en-US/Making_Modules.adoc index 840078c..2f46c9a 100644 --- a/en-US/Making_Modules.adoc +++ b/en-US/Making_Modules.adoc @@ -16,7 +16,7 @@ Such scheme is very straighforward, but limits us in two ways: === Modular builds -image::modularity-building-modules.png[,90%,] +image::modularity-building-modules.png[,90%,] Modularity introduces some new features to the build pipeline: diff --git a/en-US/References.adoc b/en-US/References.adoc index 25af978..98f7eae 100644 --- a/en-US/References.adoc +++ b/en-US/References.adoc @@ -12,3 +12,8 @@ https://pagure.io/group/modularity[Modularity on Pagure]:: https://github.com/fedora-modularity/[Modularity on GitHub]:: GitHub is an alternative place for some of our repositories. + +== Other teams and working groups + +https://fedoraproject.org/wiki/SELinuxModularity[Modularity and SELinux]:: + Documents related to SELinux support in Modularity \ No newline at end of file diff --git a/en-US/making-modules/Adding_modules_to_fedora.adoc b/en-US/making-modules/Adding_modules_to_fedora.adoc new file mode 100644 index 0000000..e69de29 --- /dev/null +++ b/en-US/making-modules/Adding_modules_to_fedora.adoc diff --git a/en-US/making-modules/Building_and_installing.adoc b/en-US/making-modules/Building_and_installing.adoc new file mode 100644 index 0000000..2419049 --- /dev/null +++ b/en-US/making-modules/Building_and_installing.adoc @@ -0,0 +1,13 @@ += Building and installing modules + +=== Runtime + +* can use packages from the base as dependencies +* can use other module streams as dependencies +* can override/replace other packages in base + +=== Build + +* can use packages from the base as build dependencies +* can use other module streams as build dependencies +* can expand across multiple modules or bases (one source produces several binaries, Stream Expansion) \ No newline at end of file diff --git a/en-US/making-modules/Building_modules_locally.adoc b/en-US/making-modules/Building_modules_locally.adoc new file mode 100644 index 0000000..6b85ad5 --- /dev/null +++ b/en-US/making-modules/Building_modules_locally.adoc @@ -0,0 +1,3 @@ += Building modules locally + +TBD \ No newline at end of file diff --git a/en-US/making-modules/Creating_sources.adoc b/en-US/making-modules/Creating_sources.adoc new file mode 100644 index 0000000..47053e3 --- /dev/null +++ b/en-US/making-modules/Creating_sources.adoc @@ -0,0 +1,3 @@ += Writing and validating modulemd + +TBD \ No newline at end of file diff --git a/en-US/making-modules/Naming_and_organizing_modules.adoc b/en-US/making-modules/Naming_and_organizing_modules.adoc new file mode 100644 index 0000000..935609f --- /dev/null +++ b/en-US/making-modules/Naming_and_organizing_modules.adoc @@ -0,0 +1,54 @@ += Naming and organizing modules + +*Modules* are organized into *streams* which are different variants (mostly major versions) of a given module. + +The full unique module identifier has these five properties: _name_, _stream_, _version_, _context_, and _architecture_. + +== Source level ID + +At the source level, modules are only identified by the first three: _name_, _stream_, and _version_. + +=== Name + +Name of the module corresponds to the name of the application or the language stack it represents. + +An example of a name could be _postgresql_ for a PostgreSQL database module, or _nodejs_ for a Node.js runtime. + +=== Stream + +Streams are variants of a module with a certain promise. + +In most cases, streams promise *backwards compatibility* with a major version of the application or the language stack they provide. For example, let's say the Node.js runtime is supported in two major versions: 6 and 8. In this case, the module _nodejs_ would have two streams: _6_ and _8_. + +However, streams can also promise different things such as *stability*. A good example of this is the _calc_ package in Fedora which is maintained in two upstream branches: _stable_ for the latest stable release and _unstable_ for the latest development version. Using modularity, this package could be built as a _calc_ module in two different streams: _stable_ and _unstable_. + +In addition to the version promise, streams are also a way for packagers to communicate the *level of maintennance*. Does the maintainer plan to apply every minor patch? Will they apply security fixes quickly? Or is the module updated only twice a year? This can also be part of the promise. + +Other different example could be a stream that provides the software compiled using some experimental flags increasing the performance. + +Anyway, you get the idea. Streams are very flexible and powerful tool. Use them wisely. + +=== Version + +Versions are just updates of a given stream. Technically, version is a number generated by the build system. Higher number always wins. + +== Binary level ID + +Building a module from one source can result in multiple different binaries. Different binaries are typically produced for different architectures (i.e. _x86_64_, _armv7hl_, etc.) and different Fedora releases (i.e. Fedora 28, Fedora 29, EPEL 7, etc.). + +In addition to the _name_, _stream_, and _version_ fields described above, there are two more for binaries: + +=== Architecture + +https://fedoraproject.org/wiki/Architectures[ Fedora is built for many different architectures]. The architecture field simply distinguishes architecture-specific binaries from each other. + +The value is typically the same as with RPM packages, i.e. _x86_64_, _armv7hl_, etc. + +=== Context + +Context is used to distinguish binaries built for different Fedora releases. Thanks to https://fedoraproject.org/wiki/Infrastructure/Factory2/Focus/StreamExpansion[stream expansion], modules can also be built against multiple streams of other modules, i.e. different versions of a language runtime etc. + +The value is generated by the build system and is usually hidden from the user as it doesn't have any informational value by itself — it is a hash. However, the client tooling consuming this valie can present it in a useful way. + +One way of representing the context could be listing the Fedora releases for which a certain module has been built. + diff --git a/en-US/making-modules/Requesting_repositories.adoc b/en-US/making-modules/Requesting_repositories.adoc new file mode 100644 index 0000000..8b37cf7 --- /dev/null +++ b/en-US/making-modules/Requesting_repositories.adoc @@ -0,0 +1,3 @@ += Requesting dist-git branches + +TBD \ No newline at end of file diff --git a/en-US/making-modules/Storing_and_defining_sources.adoc b/en-US/making-modules/Storing_and_defining_sources.adoc new file mode 100644 index 0000000..ab6dffa --- /dev/null +++ b/en-US/making-modules/Storing_and_defining_sources.adoc @@ -0,0 +1,124 @@ += Storing and defining module sources + +Module sources consist of two main parts: + +. RPM package sources +. module definition file + +Both of these are stored in https://src.fedoraproject.org/[Fedora dist-git]. Dist-git is organized into repositories, each having multiple branches. + +== Stream branching + +Modularity introduced https://fedoraproject.org/wiki/Changes/ArbitraryBranching[Stream Branching] (formerly Arbitrary Branching) that is used for both module definitions and RPM packages that are part of modules. + +=== Modules + +Module definitions are stored in the `/modules` namespace and only consist of a modulemd file that defines the module itself. + +Each module has a repository with branches corresponding to different streams. The repository and branch naming map to the module ID: + +* Repository name -> module name +* Branch name -> stream name +* Commit timestamp -> module version + +=== Packages + +RPM Packages are stored in the `/rpms` namespace, and are also organized into stream branches. However, only the repository name map to the name of the package: + +* Repository name -> package name +* Branch name doesn't map to anything, but is used as a reference in the module definition. + +== Defining modules using modulemd + +Modules are defined using a https://pagure.io/modulemd[modulemd file]. It defines the following information: + +* summary and description +* list of components (srpm name + branch) +* "build" information +** build groups +** filter +** macros +** dependencies +* "use" information +** installation profiles +** licenses +** refs to community, docs, bug tracker +** API + +=== Example + +WARNING: The following example is modulemd version 1 that doesn't support stream expansion. We are introducing a new version very soon. + +modulemd.yaml +[source,yaml] +---- +document: modulemd +version: 1 +data: + summary: An example module <1> + description: >- + A module for the demonstration <2> + of the metadata format. + license: + module: + - MIT <3> + dependencies: <4> + buildrequires: + platform: f27 + requires: + platform: f27 + references: <5> + community: http://www.example.com/ + documentation: http://www.example.com/ + tracker: http://www.example.com/ + profiles: <6> + default: + rpms: + - foo + - foo-extras + minimal: + description: Minimal profile. + rpms: + - foo + api: <7> + rpms: + - foo + components: <8> + rpms: + foo: <9> + rationale: Our main package. <10> + ref: 2.4 <11> + bar: + rationale: Some another package. + ref: latest +---- + +<1> A short summary describing the module. + +<2> A longer summary describing the module. + +<3> Licence of this modulemd file. + +<4> Other modules and their streams that are used as runtime and build dependencies. +"platform" is a reserved word for the Fedora releases. +The stream names follow the usual short names for the releases i.e. "f26", "f27", "epel7", etc. +In this version of modulemd (v1) there is no support for stream expansion. +That means that only one release can be selected. +However, in the upcoming version of modulemd (v2) there will be an option to list multiple ones. + +<5> Various references to the upstream. + +<6> Installation profiles that will help users to install the module. +Keep in mind that not all the packages from the module need to be installed. + +<7> The module's public RPM-level API. +A list of binary RPM names that are considered to be the main and stable feature of the module + +<8> List of packages that are part of this module. + +<9> Name of a package. + +<10> A rationale why the package has been included. +This is only for humans. + +<11> A dist-git branch of the package. \ No newline at end of file diff --git a/en-US/making-modules/Submitting_builds.adoc b/en-US/making-modules/Submitting_builds.adoc new file mode 100644 index 0000000..6f2c693 --- /dev/null +++ b/en-US/making-modules/Submitting_builds.adoc @@ -0,0 +1,3 @@ += Submitting module builds + +TBD \ No newline at end of file diff --git a/en-US/making-modules/Updating_modules.adoc b/en-US/making-modules/Updating_modules.adoc new file mode 100644 index 0000000..71b7b9b --- /dev/null +++ b/en-US/making-modules/Updating_modules.adoc @@ -0,0 +1,3 @@ += Updating modules using Bodhi + +TBD \ No newline at end of file diff --git a/en-US/making-modules/adding_modules_to_fedora.adoc b/en-US/making-modules/adding_modules_to_fedora.adoc deleted file mode 100644 index 0df26fe..0000000 --- a/en-US/making-modules/adding_modules_to_fedora.adoc +++ /dev/null @@ -1 +0,0 @@ -= Adding a module to Fedora \ No newline at end of file diff --git a/en-US/making-modules/defining.adoc b/en-US/making-modules/defining.adoc deleted file mode 100644 index f4a694f..0000000 --- a/en-US/making-modules/defining.adoc +++ /dev/null @@ -1,94 +0,0 @@ -= Defining modules using modulemd - -Modules are defined using a https://pagure.io/modulemd[modulemd file]. It defines the following information: - -* summary and description -* list of components (srpm name + branch) -* "build" information -** build groups -** filter -** macros -** dependencies -* "use" information -** installation profiles -** licenses -** refs to community, docs, bug tracker -** API - -A minimal example: - -WARNING: The following example is modulemd version 1 that doesn't support stream expansion. We are introducing a new version very soon. - -modulemd.yaml -[source,yaml] ----- -document: modulemd -version: 1 -data: - summary: An example module <1> - description: >- - A module for the demonstration <2> - of the metadata format. - license: - module: - - MIT <3> - dependencies: <4> - buildrequires: - platform: f27 - requires: - platform: f27 - references: <5> - community: http://www.example.com/ - documentation: http://www.example.com/ - tracker: http://www.example.com/ - profiles: <6> - default: - rpms: - - foo - - foo-extras - minimal: - description: Minimal profile. - rpms: - - foo - api: <7> - rpms: - - foo - components: <8> - rpms: - foo: <9> - rationale: Our main package. <10> - ref: 2.4 <11> - bar: - rationale: Some another package. - ref: latest ----- - -<1> A short summary describing the module. - -<2> A longer summary describing the module. - -<3> Licence of this modulemd file. - -<4> Other modules and their streams that are used as runtime and build dependencies. -"platform" is a reserved word for the Fedora releases. -The stream names follow the usual short names for the releases i.e. "f26", "f27", "epel7", etc. -In this version of modulemd (v1) there is no support for stream expansion. -That means that only one release can be selected. -However, in the upcoming version of modulemd (v2) there will be an option to list multiple ones. - -<5> Various references to the upstream. - -<6> Installation profiles that will help users to install the module. -Keep in mind that not all the packages from the module need to be installed. - -<7> The module's public RPM-level API. -A list of binary RPM names that are considered to be the main and stable feature of the module - -<8> List of packages that are part of this module. - -<9> Name of a package. - -<10> A rationale why the package has been included. -This is only for humans. - -<11> A dist-git branch of the package. \ No newline at end of file diff --git a/en-US/making-modules/facts.adoc b/en-US/making-modules/facts.adoc deleted file mode 100644 index 894d026..0000000 --- a/en-US/making-modules/facts.adoc +++ /dev/null @@ -1,15 +0,0 @@ -= Building and installing modules - -== How module interacts with the base and other modules - -=== Runtime - -* can use packages from the base as dependencies -* can use other module streams as dependencies -* can override/replace other packages in base - -=== Build - -* can use packages from the base as build dependencies -* can use other module streams as build dependencies -* can expand across multiple modules or bases (one source produces several binaries, Stream Expansion) \ No newline at end of file diff --git a/en-US/making-modules/how.adoc b/en-US/making-modules/how.adoc deleted file mode 100644 index 5ac6996..0000000 --- a/en-US/making-modules/how.adoc +++ /dev/null @@ -1,9 +0,0 @@ -= How to make a module - -If you have decided you want to make a module: - -. Understand what modules are and how they are organized. -. Learn about how Fedora stores module sources in dist-git. -. Learn about the module definition file — modulemd. -. Learn about how modules are built and installed. -. See the WHAT (guides) section for specific end-to-end guides. \ No newline at end of file diff --git a/en-US/making-modules/local_builds.adoc b/en-US/making-modules/local_builds.adoc deleted file mode 100644 index 6b85ad5..0000000 --- a/en-US/making-modules/local_builds.adoc +++ /dev/null @@ -1,3 +0,0 @@ -= Building modules locally - -TBD \ No newline at end of file diff --git a/en-US/making-modules/module_updates.adoc b/en-US/making-modules/module_updates.adoc deleted file mode 100644 index 71b7b9b..0000000 --- a/en-US/making-modules/module_updates.adoc +++ /dev/null @@ -1,3 +0,0 @@ -= Updating modules using Bodhi - -TBD \ No newline at end of file diff --git a/en-US/making-modules/requesting_branches.adoc b/en-US/making-modules/requesting_branches.adoc deleted file mode 100644 index 8b37cf7..0000000 --- a/en-US/making-modules/requesting_branches.adoc +++ /dev/null @@ -1,3 +0,0 @@ -= Requesting dist-git branches - -TBD \ No newline at end of file diff --git a/en-US/making-modules/source.adoc b/en-US/making-modules/source.adoc deleted file mode 100644 index c88af2c..0000000 --- a/en-US/making-modules/source.adoc +++ /dev/null @@ -1,29 +0,0 @@ -= Storing module sources - -Module sources consist of two main parts: - -. RPM package sources -. module definition file - -Both of these are stored in https://src.fedoraproject.org/[Fedora dist-git]. Dist-git is organized into repositories, each having multiple branches. - -== Stream branching - -Modularity introduced https://fedoraproject.org/wiki/Changes/ArbitraryBranching[Stream Branching] (formerly Arbitrary Branching) that is used for both module definitions and RPM packages that are part of modules. - -=== Modules - -Module definitions are stored in the `/modules` namespace and only consist of a modulemd file that defines the module itself. - -Each module has a repository with branches corresponding to different streams. The repository and branch naming map to the module ID: - -* Repository name -> module name -* Branch name -> stream name -* Commit timestamp -> module version - -=== Packages - -RPM Packages are stored in the `/rpms` namespace, and are also organized into stream branches. However, only the repository name map to the name of the package: - -* Repository name -> package name -* Branch name doesn't map to anything, but is used as a reference in the module definition. \ No newline at end of file diff --git a/en-US/making-modules/submitting_builds.adoc b/en-US/making-modules/submitting_builds.adoc deleted file mode 100644 index 6f2c693..0000000 --- a/en-US/making-modules/submitting_builds.adoc +++ /dev/null @@ -1,3 +0,0 @@ -= Submitting module builds - -TBD \ No newline at end of file diff --git a/en-US/making-modules/understanding.adoc b/en-US/making-modules/understanding.adoc deleted file mode 100644 index bee6689..0000000 --- a/en-US/making-modules/understanding.adoc +++ /dev/null @@ -1,59 +0,0 @@ -= Understanding modules - -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. - -Modules are made available in multiple streams (see below) and have independent lifecycles from the base distribution. - - -== Identifying and organizing modules - -Modules are uniquely identified by five properties: _name_, _stream_, _version_, _context_, and _architecture_. - -=== Source level ID - -At the source level, modules are only identified by the first three: _name_, _stream_, and _version_. - -==== Name - -Name of the module corresponds to the name of the application or the language stack it represents. - -An example of a name could be _postgresql_ for a PostgreSQL database module, or _nodejs_ for a Node.js runtime. - -==== Stream - -Streams are variants of a module with a certain promise. - -In most cases, streams promise *backwards compatibility* with a major version of the application or the language stack they provide. For example, let's say the Node.js runtime is supported in two major versions: 6 and 8. In this case, the module _nodejs_ would have two streams: _6_ and _8_. - -However, streams can also promise different things such as *stability*. A good example of this is the _calc_ package in Fedora which is maintained in two upstream branches: _stable_ for the latest stable release and _unstable_ for the latest development version. Using modularity, this package could be built as a _calc_ module in two different streams: _stable_ and _unstable_. - -In addition to the version promise, streams are also a way for packagers to communicate the *level of maintennance*. Does the maintainer plan to apply every minor patch? Will they apply security fixes quickly? Or is the module updated only twice a year? This can also be part of the promise. - -Other different example could be a stream that provides the software compiled using some experimental flags increasing the performance. - -Anyway, you get the idea. Streams are very flexible and powerful tool. Use them wisely. - -==== Version - -Versions are just updates of a given stream. Technically, version is a number generated by the build system. Higher number always wins. - -=== Binary level ID - -Building a module from one source can result in multiple different binaries. Different binaries are typically produced for different architectures (i.e. _x86_64_, _armv7hl_, etc.) and different Fedora releases (i.e. Fedora 28, Fedora 29, EPEL 7, etc.). - -In addition to the _name_, _stream_, and _version_ fields described above, there are two more for binaries: - -==== Architecture - -https://fedoraproject.org/wiki/Architectures[ Fedora is built for many different architectures]. The architecture field simply distinguishes architecture-specific binaries from each other. - -The value is typically the same as with RPM packages, i.e. _x86_64_, _armv7hl_, etc. - -==== Context - -Context is used to distinguish binaries built for different Fedora releases. Thanks to https://fedoraproject.org/wiki/Infrastructure/Factory2/Focus/StreamExpansion[stream expansion], modules can also be built against multiple streams of other modules, i.e. different versions of a language runtime etc. - -The value is generated by the build system and is usually hidden from the user as it doesn't have any informational value by itself — it is a hash. However, the client tooling consuming this valie can present it in a useful way. - -One way of representing the context could be listing the Fedora releases for which a certain module has been built. - diff --git a/en-US/making-modules/what.adoc b/en-US/making-modules/what.adoc deleted file mode 100644 index e3b957b..0000000 --- a/en-US/making-modules/what.adoc +++ /dev/null @@ -1,7 +0,0 @@ -= What to do to make modules - -This section contains end-to-end guides to solve a particular user story such as: - -* Requesting new dist-git stream branches for modules and packages -* Building a module for the first time -* Submitting a module update \ No newline at end of file diff --git a/en-US/making-modules/why.adoc b/en-US/making-modules/why.adoc deleted file mode 100644 index 8ca30ee..0000000 --- a/en-US/making-modules/why.adoc +++ /dev/null @@ -1,11 +0,0 @@ -= Why to make a module - -Main reasons: - -* additional version -* lifecycle independent from the core / base OS - -Other reasons: - -* help users with installing a multipackage "thing" -* maintaining one source for multiple Fedora releases \ No newline at end of file diff --git a/en-US/making-modules/writing_and_validating_modulemd.adoc b/en-US/making-modules/writing_and_validating_modulemd.adoc deleted file mode 100644 index 47053e3..0000000 --- a/en-US/making-modules/writing_and_validating_modulemd.adoc +++ /dev/null @@ -1,3 +0,0 @@ -= Writing and validating modulemd - -TBD \ No newline at end of file From 2824141141456dbdf73377b9b74ded78e23f4095 Mon Sep 17 00:00:00 2001 From: Adam Samalik Date: Mar 13 2018 14:46:34 +0000 Subject: [PATCH 7/9] update CSS --- diff --git a/_images/docs_logo.png b/_images/docs_logo.png new file mode 100644 index 0000000..90421ec Binary files /dev/null and b/_images/docs_logo.png differ diff --git a/_images/docs_logo.svg b/_images/docs_logo.svg new file mode 100644 index 0000000..476b13a --- /dev/null +++ b/_images/docs_logo.svg @@ -0,0 +1,158 @@ + + + + + + + + + + image/svg+xml + + + + + + + + + DOCS + + + + + + + + + + + + + + + + + + + + + + + diff --git a/_stylesheets/asciibinder.css b/_stylesheets/asciibinder.css index 31dba30..dff4ea9 100644 --- a/_stylesheets/asciibinder.css +++ b/_stylesheets/asciibinder.css @@ -73,35 +73,62 @@ License: https://creativecommons.org/licenses/by/2.0/ font-size: 28px; } -.page-header { - height: 100% !important; -} .page-header .img-responsive { display: inline; } -.page-header h2 { - font-size: 32px; - display: inline; - vertical-align: bottom; + +.docs-content h1, +.docs-content h2, +.docs-content h3, +.docs-content h4, +.docs-content h5, +.docs-content h6 + { + font-weight: bold; + color: #444; +} + +.docs-content h1{ + font-size: 1.5rem +} +.docs-content h2{ + font-size: 1.3rem +} +.docs-content h3{ + font-size: 1.1rem +} +.docs-content h4, +.docs-content h5, +.docs-content h6{ + font-size: 1rem; } -.navbar-brand { - padding: initial; - height: initial; - padding: 12px; +.docs-content .page-header h1 { + line-height: 1.5rem; + padding-bottom: 0.2em; + margin-bottom: 0.7em; + border-bottom: 1px solid #ccc; + } -.navbar-header h2 { - display: inline; - position: absolute; - font-weight: bold; - margin-top: 50px ; + +nav .breadcrumb{ + background: none; + font-size:0.8em; + padding-left:10px; + padding-bottom:0px; } .nav > li > a.hover{ background-color: none; } +.breadcrumb-item + .breadcrumb-item::before{ + content: '\f054'; + font-family: FontAwesome; + font-size: 0.8em; +} + h1, h2, h3, h4, h5, h6, .h1, .h2, .h3, .h4, .h5, .h6 { position: relative; } @@ -158,21 +185,47 @@ h6 > a.anchor:hover { } } +.masthead, .footer{ + position: relative; + z-index: 1; +} + +.footer a{ + color:#aaa +} + +.footer{ + font-size:0.8em; + box-shadow: 0px 1000px 0px 1000px #495057; +} + +.footer h3{ + font-size:1.3em; + font-weight: bold; + text-transform: uppercase; +} + /* * Sidebar */ + .docs-sidebar{ + background: #eee; + box-shadow: -3000px 0 0 3000px #eee; + } + .nav-header { font-size: 16px; } .nav-header ul { font-size: 14px; + padding-left:1em; } .nav-header ul li a { display: block; - padding: 5px 20px 5px 25px; + padding: 3px 0px 4px 7px; font-size: 13px; font-weight: normal; } @@ -183,8 +236,8 @@ h6 > a.anchor:hover { width: 14px; } -.nav-sidebar li a { - color: inherit; +.docs-sidebar li a { + color: #555; } .nav-sidebar li a:hover { @@ -223,66 +276,6 @@ h6 > a.anchor:hover { } } -/* - * Off Canvas - * -------------------------------------------------- - */ - -body, html { - overflow-x: hidden; /* Prevent scroll on narrow devices */ - font-family: "Overpass", sans-serif; -} - -.toggle-nav { - margin-right: 20px; -} - -@media screen and (max-width: 767px) { - .row-offcanvas { - position: relative; - -webkit-transition: all .25s ease-out; - -o-transition: all .25s ease-out; - transition: all .25s ease-out; - } - - .row-offcanvas-right { - right: 0; - } - - .row-offcanvas-left { - left: 0; - } - - .row-offcanvas-right - .sidebar-offcanvas { - right: -75%; /* 8 columns */ - } - - .row-offcanvas-left - .sidebar-offcanvas { - left: -75%; /* 8 columns */ - } - - .row-offcanvas-right.active { - right: 75%; /* 8 columns */ - } - - .row-offcanvas-left.active { - left: 75%; /* 8 columns */ - } - - .sidebar-offcanvas { - overflow: hidden; - position: absolute; - top: 0; - width: 75%; /* 8 columns */ - } -} - - p { - margin: 0 0 1.6em; - } - /* Remnants of Asciidoctor default stylesheet - remove styles as needed */ #map_canvas img, #map_canvas embed, #map_canvas object, .map_canvas img, .map_canvas embed, .map_canvas object { max-width: none !important; } diff --git a/_templates/_breadcrumb.html.erb b/_templates/_breadcrumb.html.erb new file mode 100644 index 0000000..70a9e5e --- /dev/null +++ b/_templates/_breadcrumb.html.erb @@ -0,0 +1,14 @@ +<%- navigation.each do |topic_group| -%> + <%- if topic_id.start_with?(topic_group[:id]) %> + + <%- end -%> + <%- if topic_group.has_key?(:topics) -%> + <%= render("_templates/_breadcrumb.html.erb", :navigation => topic_group[:topics], :topic_id => topic_id, :subtopic_shim => subtopic_shim) %> + <%- end -%> +<%- end -%> diff --git a/_templates/_nav.html.erb b/_templates/_nav.html.erb index 95a7e5c..b622156 100644 --- a/_templates/_nav.html.erb +++ b/_templates/_nav.html.erb @@ -1,31 +1,18 @@ - +<%- end -%> diff --git a/_templates/_title.html.erb b/_templates/_title.html.erb new file mode 100644 index 0000000..ff3eaa8 --- /dev/null +++ b/_templates/_title.html.erb @@ -0,0 +1,8 @@ +<%- navigation.each do |topic_group| -%> + <%- if topic_id.start_with?(topic_group[:id]) %> + | <%= topic_group[:name] %> + <%- end -%> + <%- if topic_group.has_key?(:topics) -%> + <%= render("_templates/_title.html.erb", :navigation => topic_group[:topics], :topic_id => topic_id) %> + <%- end -%> +<%- end -%> diff --git a/_templates/page.html.erb b/_templates/page.html.erb index 06a4c85..c8f0018 100644 --- a/_templates/page.html.erb +++ b/_templates/page.html.erb @@ -7,11 +7,9 @@ <%= distro %> <%= version %> | <%= [group_title, subgroup_title, topic_title].compact.join(' | ') %> - - + - - + <%= render("_templates/_css.html.erb", :css_path => css_path) %> @@ -22,7 +20,7 @@ - " rel="shortcut icon" type="text/css"> + " rel="shortcut icon" type="text/css"> @@ -30,88 +28,56 @@ <%- if version == "Rawhide" %>
">Improve this Page
<%- end %> -