From c4500d3c83dcd1fceabd7d54759301d946c94c50 Mon Sep 17 00:00:00 2001 From: Adam Samalik Date: Jul 27 2018 12:37:19 +0000 Subject: [PATCH 1/2] migrate to antora --- diff --git a/.gitignore b/.gitignore index 462d167..9f3ebf5 100644 --- a/.gitignore +++ b/.gitignore @@ -1,9 +1,3 @@ -## AsciiBinder-specific ignores -_preview -_package -*.swp -diag-*.png -diag-*.png.cache - -## Project-specific ignores - +build +cache +public diff --git a/Common_Content/Feedback.adoc b/Common_Content/Feedback.adoc deleted file mode 100644 index d11787f..0000000 --- a/Common_Content/Feedback.adoc +++ /dev/null @@ -1,26 +0,0 @@ - -:experimental: - -=== We want feedback -indexterm:[feedback,contact information for this manual] -If you find errors or have suggestions for improvement, we want your advice. Submit a report in Bugzilla against the product `{PRODUCT}` and the component `{BOOKID}`. The following link automatically loads this information for you: {BZURL}. - -In Bugzilla: - -. Provide a short summary of the error or your suggestion in the `Summary` field. - -. Copy the following template into the `Description` field and give us the details of the error or suggestion as specifically as you can. If possible, include some surrounding text so we know where the error occurs or the suggestion fits. -+ -[subs="quotes"] ----- -Document URL: - -Section number and name: - -Error or suggestion: - -Additional information: - ----- - -. Click the btn:[Submit Bug] button. diff --git a/Common_Content/Legal_Notice.adoc b/Common_Content/Legal_Notice.adoc deleted file mode 100644 index b65d4a5..0000000 --- a/Common_Content/Legal_Notice.adoc +++ /dev/null @@ -1,22 +0,0 @@ - -:experimental: - -Copyright {YEAR} {HOLDER}. - -The text of and illustrations in this document are licensed by Red Hat under a Creative Commons Attribution–Share Alike 3.0 Unported license ("CC-BY-SA"). An explanation of CC-BY-SA is available at link:++http://creativecommons.org/licenses/by-sa/3.0/++[]. The original authors of this document, and Red Hat, designate the Fedora Project as the "Attribution Party" for purposes of CC-BY-SA. In accordance with CC-BY-SA, if you distribute this document or an adaptation of it, you must provide the URL for the original version. - -Red Hat, as the licensor of this document, waives the right to enforce, and agrees not to assert, Section 4d of CC-BY-SA to the fullest extent permitted by applicable law. - -Red Hat, Red Hat Enterprise Linux, the Shadowman logo, JBoss, MetaMatrix, Fedora, the Infinity Logo, and RHCE are trademarks of Red Hat, Inc., registered in the United States and other countries. - -For guidelines on the permitted uses of the Fedora trademarks, refer to link:++https://fedoraproject.org/wiki/Legal:Trademark_guidelines++[]. - -*Linux* (R) is the registered trademark of Linus Torvalds in the United States and other countries. - -*Java* (R) is a registered trademark of Oracle and/or its affiliates. - -*XFS* (R) is a trademark of Silicon Graphics International Corp. or its subsidiaries in the United States and/or other countries. - -*MySQL* (R) is a registered trademark of MySQL AB in the United States, the European Union and other countries. - -All other trademarks are the property of their respective owners. diff --git a/Common_Content/images/title_logo.svg b/Common_Content/images/title_logo.svg deleted file mode 100644 index e8fd52b..0000000 --- a/Common_Content/images/title_logo.svg +++ /dev/null @@ -1,61 +0,0 @@ - - - - - - - - - - - - - - - - - - - diff --git a/README.md b/README.md index 2e67559..82ad1f6 100644 --- a/README.md +++ b/README.md @@ -16,20 +16,28 @@ markup language. You may want to look at: * [AsciiDoc Syntax Quick Reference](http://asciidoctor.org/docs/asciidoc-syntax-quick-reference/) * [AsciiDoc Writer’s Guide](http://asciidoctor.org/docs/asciidoc-writers-guide/) -* [Asciidoctor Diagram](http://asciidoctor.org/docs/asciidoctor-diagram/) (We use ditaa) +* [Antora Documentation](https://docs.antora.org/antora/1.0/page/) -## Testing your changes locally -To test your changes, first install `asciibinder` +## Local preview -$ gem install ascii_binder +This repo includes scripts to build and preview the contents of this repository. -To build your changes, from the root directory: +**NOTE**: Please note that if you reference pages from other repositoreis, such links will be broken in this local preview as it only builds this repository. If you want to rebuild the whole Fedora Docs site, please see [the Fedora Docs build repository](https://pagure.io/fedora-docs/docs-fp-o/) for instructions. + +Both scripts use docker, so please make sure you have it installed on your system. Please see below for instructions. + +To build and preview the site, run: ``` -$ asciibinder package -$ firefox _package/main/index.html +$ ./build.sh && ./preview.sh ``` -**Help wanted**: We need Ruby packaging experts to [help us get asciibinder into Fedora as an -RPM](https://lists.fedoraproject.org/archives/list/ruby-sig@lists.fedoraproject.org/message/7ZWMVGQ3RXDWAJNP3OOZXBC57SYB5IF5/). +The result will be available at http://localhost:8080 + +### Installing docker on Fedora + +``` +$ sudo dnf install docker +$ sudo systemctl start docker && sudo systemctl enable docker +``` diff --git a/_distro_map.yml b/_distro_map.yml deleted file mode 100644 index 978d242..0000000 --- a/_distro_map.yml +++ /dev/null @@ -1,11 +0,0 @@ ---- -fedora: - name: Fedora Modularity Docs - author: Fedora Documentation Project - site: main - site_name: Home - site_url: https://docs.fedoraproject.org/ - branches: - master: - name: - dir: master diff --git a/_images/404.html b/_images/404.html deleted file mode 100644 index f72f371..0000000 --- a/_images/404.html +++ /dev/null @@ -1,135 +0,0 @@ - - - - - - - - - Fedora Documentation Website - - - - - - - - - - - - - -
-
-
- -

Fedora Documentation Site

-
-
-
-
-

Fedora Documentation - 404 Page Not Found :(

-

Hi! You've arrived at Fedora documentation page which does not actually exist. This may be because you followed a link to an older document which has been retired. For reference, you can find those in our old document archive. Or, you can browse current docs.

-

It may also be that this page _should_ exist, but sadly does not. If this is the case, and you know what it should say, you can contribute via the Docs Project.

-
-
-
- -
-
-
-
-
-

About

-
-
-
About Fedora
-
Sponsors
-
Fedora Magazine
-
Legal
-
-
    -
  • - -
    • -
  • - -
    • -
  • - -
    • -
-
-
- -
-

Download

-
-
-
Get Fedora Workstation
-
Get Fedora Server
-
Get Fedora Atomic
-
Fedora Spins
-
Fedora Labs
-
Fedora ARM®
-
Alternative Downloads
- -
-
-
- -
-

Support

-
-
-
Get Help
-
Ask Fedora
-
Common Bugs
-
Fedora Developer Portal
-
Installation Guide
-
-
-
- -
-

Join

-
-
-
Join Fedora
-
Planet Fedora
-
Fedora SIGs
-
Fedora Account System
-
Fedora Community
-
-
-
-
- -
-
-
- -
-
-
-
- - -

© 2017 Red Hat, Inc. and others. Please send any comments or corrections to the documentation team

-
-
-
- -
-
-
- - - - - - diff --git a/_images/docs_logo.png b/_images/docs_logo.png deleted file mode 100644 index 90421ec..0000000 Binary files a/_images/docs_logo.png and /dev/null differ diff --git a/_images/docs_logo.svg b/_images/docs_logo.svg deleted file mode 100644 index 476b13a..0000000 --- a/_images/docs_logo.svg +++ /dev/null @@ -1,158 +0,0 @@ - - - - - - - - - - image/svg+xml - - - - - - - - - DOCS - - - - - - - - - - - - - - - - - - - - - - - diff --git a/_images/favicon.ico b/_images/favicon.ico deleted file mode 100644 index a912017..0000000 Binary files a/_images/favicon.ico and /dev/null differ diff --git a/_images/favicon32x32.png b/_images/favicon32x32.png deleted file mode 100644 index d33bd5e..0000000 Binary files a/_images/favicon32x32.png and /dev/null differ diff --git a/_images/fedora.svg b/_images/fedora.svg deleted file mode 100644 index e8fd52b..0000000 --- a/_images/fedora.svg +++ /dev/null @@ -1,61 +0,0 @@ - - - - - - - - - - - - - - - - - - - diff --git a/_images/redhat-logo.png b/_images/redhat-logo.png deleted file mode 100644 index f085f1a..0000000 Binary files a/_images/redhat-logo.png and /dev/null differ diff --git a/_javascripts/.gitkeep b/_javascripts/.gitkeep deleted file mode 100644 index e69de29..0000000 --- a/_javascripts/.gitkeep +++ /dev/null diff --git a/_javascripts/bootstrap-offcanvas.js b/_javascripts/bootstrap-offcanvas.js deleted file mode 100644 index 62cf7b6..0000000 --- a/_javascripts/bootstrap-offcanvas.js +++ /dev/null @@ -1,6 +0,0 @@ -$(document).ready(function () { - $('[data-toggle="offcanvas"]').click(function () { - $('.sidebar').show(); - $('.row-offcanvas').toggleClass('active'); - }); -}); diff --git a/_stylesheets/asciibinder.css b/_stylesheets/asciibinder.css deleted file mode 100644 index dff4ea9..0000000 --- a/_stylesheets/asciibinder.css +++ /dev/null @@ -1,591 +0,0 @@ -@import url(https://maxcdn.bootstrapcdn.com/font-awesome/4.1.0/css/font-awesome.min.css); -/* ------------------------------------------------------------ -Image: "Spin" https://www.flickr.com/photos/eflon/3655695161/ -Author: eflon https://www.flickr.com/photos/eflon/ -License: https://creativecommons.org/licenses/by/2.0/ ----------------------------------------------------------------*/ -.attribution { - text-align: center; - position: relative; - bottom: -20px; -} -.attribution .btn { - color: #808080; - color: rgba(175,175,175, .65); - font-size: 11px; -} -.attribution .btn:hover { - text-decoration: none; - color: #aaa; -} -.popover-content { - font-size: 12px; - line-height: 1.3; - font-weight: normal; -} - -@media screen and (max-width: 980px) { - body { - margin-bottom: 200px; - } - footer { - text-align: center; - } - footer .text-right { - text-align: center !important; - } - #footer_social .first { - margin-left: 0; - } - #footer_social > a { - top: 24px; - } -} - -.fa-inverse:hover { - color: #ccc; -} - -.collapse a.active { - background-color: #DEEAF4; - color: #000; - position: relative; -} - -.collapse a.active:hover { - text-decoration: none; -} - -.collapse a.active:before { - background-color: #A0C3E5; - content: ""; - display: inline-block; - height: 100%; - left: 0; - position: absolute; - top: 0; - width: 3px; -} - -.main h2, .main .h2 { - border-top: 0px; - padding-top: 10px; - font-size: 28px; -} - -.page-header .img-responsive { - display: inline; -} - -.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; -} - -.docs-content .page-header h1 { - line-height: 1.5rem; - padding-bottom: 0.2em; - margin-bottom: 0.7em; - border-bottom: 1px solid #ccc; - -} - - -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; -} - -h2 > a.anchor, h3 > a.anchor, h4 > a.anchor, h5 > a.anchor, h6 > a.anchor { - display: block; - font-weight: normal; - margin-left: -1.5ex; - position: absolute; - text-align: center; - text-decoration: none !important; - visibility: hidden; - width: 1.5ex; - z-index: 1001; -} - -h2 > a.anchor:before, h3 > a.anchor:before, h4 > a.anchor:before, h5 > a.anchor:before, h6 > a.anchor:before { - content: "\f0c1"; - display: block; - font-family: FontAwesome; - font-size: 0.7em; - -webkit-font-smoothing: antialiased; - -moz-osx-font-smoothing: grayscale; - padding-top: 0.2em; -} - -h4 > a.anchor:before, h5 > a.anchor:before, h6 > a.anchor:before { - font-size: 1em; -} - -h2:hover > a.anchor, -h2 > a.anchor:hover, -h3:hover > a.anchor, -h3 > a.anchor:hover, -h4:hover > a.anchor, -h4 > a.anchor:hover, -h5:hover > a.anchor, -h5 > a.anchor:hover, -h6:hover > a.anchor, -h6 > a.anchor:hover { - visibility: visible; -} - -.main { - border-left: 1px solid #e7e7e7; - margin-left: -1px; - padding-left: 25px; -} - - -@media (min-width: 768px) { - .main { - padding-left: 30px; - } -} - -.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: 3px 0px 4px 7px; - font-size: 13px; - font-weight: normal; -} - -.nav-sidebar .fa { - text-align: center; - top: -1px; - width: 14px; -} - -.docs-sidebar li a { - color: #555; -} - -.nav-sidebar li a:hover { - color: #000; -} - -.nav-sidebar ul li ul.nav-tertiary li a { - padding-left: 50px; -} - -.nav-sidebar > li > a { - padding: 7px 0; -} - -.nav-sidebar > li > a:focus, .nav-sidebar > li > a:hover { - background: transparent; -} - -.sidebar { - font-weight: 300; - display: none; - padding-top: 13px; -} - -@media screen and (max-width: 767px) { - .sidebar { - padding-left: 30px; - padding-right: 0; - } -} - -@media screen and (min-width: 768px) { - .sidebar { - border-right: 1px solid #e7e7e7; - display: block; - } -} - - /* 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; } -.left { float: left !important; } -.right { float: right !important; } -.text-left { text-align: left !important; } -.text-right { text-align: right !important; } -.text-center { text-align: center !important; } -.text-justify { text-align: justify !important; } -.hide { display: none; } -.subheader, #content #toctitle, .admonitionblock td.content > .title, .audioblock > .title, .exampleblock > .title, .imageblock > .title, .listingblock > .title, .literalblock > .title, .stemblock > .title, .openblock > .title, .paragraph > .title, .quoteblock > .title, table.tableblock > .title, .verseblock > .title, .videoblock > .title, .dlist > .title, .olist > .title, .ulist > .title, .qlist > .title, .hdlist > .title { line-height: 1.4; color: #7a2518; font-weight: 300; margin-top: 0.2em; margin-bottom: 0.5em; } -abbr, acronym { text-transform: uppercase; font-size: 90%; color: #333333; border-bottom: 1px dotted #dddddd; cursor: help; } -abbr { text-transform: none; } -blockquote { margin: 0 0 1.25em; padding: 0.5625em 1.25em 0 1.1875em; border-left: 3px solid #487c58; } -blockquote cite { display: block; font-size: inherit; color: #454545; } -blockquote cite:before { content: "\2014 \0020"; } -blockquote cite a, blockquote cite a:visited { color: #454545; } -blockquote, blockquote p { line-height: 1.6; color: #6e6e6e; } -@media only screen and (min-width: 768px) { - #toctitle, .sidebarblock > .content > .title { line-height: 1.4; } - #toctitle, .sidebarblock > .content > .title { font-size: 1.6875em; } -} -table { background: white; margin-bottom: 1.25em; border: solid 1px #dddddd; } -table thead, table tfoot { background: whitesmoke; font-weight: bold; } -table thead tr th, table thead tr td, table tfoot tr th, table tfoot tr td { padding: 0.5em 0.625em 0.625em; font-size: inherit; color: #333333; text-align: left; } -table tr th, table tr td { padding: 0.5625em 0.625em; font-size: inherit; color: #333333; } -table tr.even, table tr.alt, table tr:nth-of-type(even) { background: #f9f9f9; } -table thead tr th, table tfoot tr th, table tbody tr td, table tr td, table tfoot tr td { display: table-cell; line-height: 1.6; } -.clearfix:before, .clearfix:after, .float-group:before, .float-group:after { content: " "; display: table; } -.clearfix:after, .float-group:after { clear: both; } -*:not(pre) > code { font-size: inherit; padding: 0; white-space: nowrap; background-color: inherit; border: 0 solid #dddddd; -webkit-border-radius: 4px; border-radius: 4px; text-shadow: none; line-height: 1; } -.keyseq { color: #666666; } -kbd:not(.keyseq) { display: inline-block; color: #333333; font-size: 0.75em; line-height: 1.4; background-color: #f7f7f7; border: 1px solid #ccc; -webkit-border-radius: 3px; border-radius: 3px; -webkit-box-shadow: 0 1px 0 rgba(0, 0, 0, 0.2), 0 0 0 2px white inset; box-shadow: 0 1px 0 rgba(0, 0, 0, 0.2), 0 0 0 2px white inset; margin: -0.15em 0.15em 0 0.15em; padding: 0.2em 0.6em 0.2em 0.5em; vertical-align: middle; white-space: nowrap; } -.keyseq kbd:first-child { margin-left: 0; } -.keyseq kbd:last-child { margin-right: 0; } -.menuseq, .menu { color: #1a1a1a; } -b.button:before, b.button:after { position: relative; top: -1px; font-weight: normal; } -b.button:before { content: "["; padding: 0 3px 0 2px; } -b.button:after { content: "]"; padding: 0 2px 0 3px; } -p a > code:hover { color: #561309; } -#header, #content, #footnotes, #footer { width: 100%; margin-left: auto; margin-right: auto; margin-top: 0; margin-bottom: 0; max-width: 62.5em; *zoom: 1; position: relative; padding-left: 0.9375em; padding-right: 0.9375em; } -#header:before, #header:after, #content:before, #content:after, #footnotes:before, #footnotes:after, #footer:before, #footer:after { content: " "; display: table; } -#header:after, #content:after, #footnotes:after, #footer:after { clear: both; } -#content:before { content: none; } -#header { margin-bottom: 2.5em; } -#header > h1 { color: black; font-weight: 300; border-bottom: 1px solid #d8d8d8; margin-bottom: -28px; padding-bottom: 32px; } -#header span { color: #6e6e6e; } -#header #revnumber { text-transform: capitalize; } -#header br { display: none; } -#header br + span { padding-left: 3px; } -#header br + span:before { content: "\2013 \0020"; } -#header br + span.author { padding-left: 0; } -#header br + span.author:before { content: ", "; } -#toc { border-bottom: 3px double #e5e5e5; padding-top: 1em; padding-bottom: 1.25em; } -#toc > ul { margin-left: 0.25em; } -#toc ul.sectlevel0 > li > a { font-style: italic; } -#toc ul.sectlevel0 ul.sectlevel1 { margin-left: 0; margin-top: 0.5em; margin-bottom: 0.5em; } -#toc ul { font-family: "Open Sans", "DejaVu Sans", "Sans", sans-serif; list-style-type: none; } -#toc a { text-decoration: none; } -#toc a:active { text-decoration: underline; } -#toctitle { color: #7a2518; } -@media only screen and (min-width: 768px) { body.toc2 { padding-left: 15em; padding-right: 0; } - #toc.toc2 { background-color: #fafaf9; position: fixed; width: 15em; left: 0; top: 0; border-right: 1px solid #e5e5e5; border-bottom: 0; z-index: 1000; padding: 1.25em 1em; height: 100%; overflow: auto; } - #toc.toc2 #toctitle { margin-top: 0; font-size: 1.2em; } - #toc.toc2 > ul { font-size: .90em; margin-bottom: 0; } - #toc.toc2 ul ul { margin-left: 0; padding-left: 1em; } - #toc.toc2 ul.sectlevel0 ul.sectlevel1 { padding-left: 0; margin-top: 0.5em; margin-bottom: 0.5em; } - body.toc2.toc-right { padding-left: 0; padding-right: 15em; } - body.toc2.toc-right #toc.toc2 { border-right: 0; border-left: 1px solid #e5e5e5; left: auto; right: 0; } } -@media only screen and (min-width: 1280px) { body.toc2 { padding-left: 20em; padding-right: 0; } - #toc.toc2 { width: 20em; } - #toc.toc2 #toctitle { font-size: 1.375em; } - #toc.toc2 > ul { font-size: 0.95em; } - #toc.toc2 ul ul { padding-left: 1.25em; } - body.toc2.toc-right { padding-left: 0; padding-right: 20em; } } -#content #toc { border-style: solid; border-width: 1px; border-color: #e3e3dd; margin-bottom: 1.25em; padding: 1.25em; background: #fafaf9; border-width: 0; -webkit-border-radius: 4px; border-radius: 4px; } -#content #toc > :first-child { margin-top: 0; } -#content #toc > :last-child { margin-bottom: 0; } -#content #toctitle { font-size: 1.375em; } -#footer { max-width: 100%; background-color: #333333; padding: 1.25em; } -#footer-text { color: #cccccc; line-height: 1.44; } -.audioblock, .imageblock, .literalblock, .listingblock, .stemblock, .verseblock, .videoblock { margin-bottom: 2.5em; } -.admonitionblock td.content > .title, .audioblock > .title, .exampleblock > .title, .imageblock > .title, .listingblock > .title, .literalblock > .title, .stemblock > .title, .openblock > .title, .paragraph > .title, .quoteblock > .title, table.tableblock > .title, .verseblock > .title, .videoblock > .title, .dlist > .title, .olist > .title, .ulist > .title, .qlist > .title, .hdlist > .title { text-rendering: optimizeLegibility; text-align: left; font-family: "Noto Serif", "DejaVu Serif", "Serif", serif; font-weight: normal; font-style: italic; } -table.tableblock > caption.title { white-space: nowrap; overflow: visible; max-width: 0; } -table.tableblock #preamble > .sectionbody > .paragraph:first-of-type p { font-size: inherit; } -.admonitionblock > table { border: 0; background: none; width: 100%; } -.admonitionblock > table td.icon { text-align: center; width: 80px; } -.admonitionblock > table td.icon img { max-width: none; } -.admonitionblock > table td.icon .title { font-weight: 300; text-transform: uppercase; } -.admonitionblock > table td.content { padding-left: 0; padding-right: 1.25em; color: #6e6e6e; } -.admonitionblock > table td.content > :last-child > :last-child { margin-bottom: 0; } -.exampleblock > .content { border-style: solid; border-width: 1px; border-color: #e6e6e6; margin-bottom: 1.25em; padding: 1.25em; background: white; -webkit-border-radius: 4px; border-radius: 4px; } -.exampleblock > .content > :first-child { margin-top: 0; } -.exampleblock > .content > :last-child { margin-bottom: 0; } -.exampleblock > .content h1, .exampleblock > .content h2, .exampleblock > .content h3, .exampleblock > .content #toctitle, .sidebarblock.exampleblock > .content > .title, .exampleblock > .content h4, .exampleblock > .content h5, .exampleblock > .content h6, .exampleblock > .content p { color: #333333; } -.exampleblock > .content h1, .exampleblock > .content h2, .exampleblock > .content h3, .exampleblock > .content #toctitle, .sidebarblock.exampleblock > .content > .title, .exampleblock > .content h4, .exampleblock > .content h5, .exampleblock > .content h6 { line-height: 1; margin-bottom: 0.625em; } -.exampleblock > .content h1.subheader, .exampleblock > .content h2.subheader, .exampleblock > .content h3.subheader, .exampleblock > .content .subheader#toctitle, .sidebarblock.exampleblock > .content > .subheader.title, .exampleblock > .content h4.subheader, .exampleblock > .content h5.subheader, .exampleblock > .content h6.subheader { line-height: 1.4; } -.exampleblock.result > .content { -webkit-box-shadow: 0 1px 8px #e3e3dd; box-shadow: 0 1px 8px #e3e3dd; } -.sidebarblock { border-style: solid; border-width: 1px; border-color: #e3e3dd; margin-top: -1.0em; margin-bottom: 1.6em; margin-left: 1em; padding: .5em; background: #F1F3F5; -webkit-border-radius: 4px; border-radius: 4px; overflow-x: auto; float: right; width: 40%; } -.sidebarblock > :first-child { margin-top: 0; } -.sidebarblock > :last-child { margin-bottom: 0; } -.sidebarblock h1, .sidebarblock h2, .sidebarblock h3, .sidebarblock #toctitle, .sidebarblock > .content > .title, .sidebarblock h4, .sidebarblock h5, .sidebarblock h6, .sidebarblock p { color: #333333; } -.sidebarblock h1, .sidebarblock h2, .sidebarblock h3, .sidebarblock #toctitle, .sidebarblock > .content > .title, .sidebarblock h4, .sidebarblock h5, .sidebarblock h6 { line-height: 1; margin-bottom: 0.625em; } -.sidebarblock h1.subheader, .sidebarblock h2.subheader, .sidebarblock h3.subheader, .sidebarblock .subheader#toctitle, .sidebarblock > .content > .subheader.title, .sidebarblock h4.subheader, .sidebarblock h5.subheader, .sidebarblock h6.subheader { line-height: 1.4; } -.sidebarblock > .content > .title { color: inherit; font-size: 28px; font-weight: 500; margin-top: 0; line-height: 1.6; } -.width50 { width: 50% ! important} -.exampleblock > .content > :last-child > :last-child, .exampleblock > .content .olist > ol > li:last-child > :last-child, .exampleblock > .content .ulist > ul > li:last-child > :last-child, .exampleblock > .content .qlist > ol > li:last-child > :last-child, .sidebarblock > .content > :last-child > :last-child, .sidebarblock > .content .olist > ol > li:last-child > :last-child, .sidebarblock > .content .ulist > ul > li:last-child > :last-child, .sidebarblock > .content .qlist > ol > li:last-child > :last-child { margin-bottom: 0; } -.literalblock pre, .literalblock pre[class], .listingblock pre, .listingblock pre[class] { border: 0px; background-color: #F0F3F5; -webkit-border-radius: 5px; border-radius: 5px; padding: 1.5em 2.5em; word-wrap: break-word; } -.literalblock pre.nowrap, .literalblock pre[class].nowrap, .listingblock pre.nowrap, .listingblock pre[class].nowrap { overflow-x: auto; white-space: pre; word-wrap: normal; } -.literalblock pre > code, .literalblock pre[class] > code, .listingblock pre > code, .listingblock pre[class] > code { display: block; } -.listingblock > .content { position: relative; } -.listingblock:hover code[class*=" language-"]:before { text-transform: uppercase; font-size: 0.9em; color: #999; position: absolute; top: 0.375em; right: 0.375em; } -.listingblock:hover code.asciidoc:before { content: "asciidoc"; } -.listingblock:hover code.clojure:before { content: "clojure"; } -.listingblock:hover code.css:before { content: "css"; } -.listingblock:hover code.go:before { content: "go"; } -.listingblock:hover code.groovy:before { content: "groovy"; } -.listingblock:hover code.html:before { content: "html"; } -.listingblock:hover code.java:before { content: "java"; } -.listingblock:hover code.javascript:before { content: "javascript"; } -.listingblock:hover code.python:before { content: "python"; } -.listingblock:hover code.ruby:before { content: "ruby"; } -.listingblock:hover code.sass:before { content: "sass"; } -.listingblock:hover code.scss:before { content: "scss"; } -.listingblock:hover code.xml:before { content: "xml"; } -.listingblock:hover code.yaml:before { content: "yaml"; } -.listingblock.terminal pre .command:before { content: attr(data-prompt); padding-right: 0.5em; color: #999; } -.listingblock.terminal pre .command:not([data-prompt]):before { content: '$'; } -table.pyhltable { border: 0; margin-bottom: 0; } -table.pyhltable td { vertical-align: top; padding-top: 0; padding-bottom: 0; } -table.pyhltable td.code { padding-left: .75em; padding-right: 0; } -.highlight.pygments .lineno, table.pyhltable td:not(.code) { color: #999; padding-left: 0; padding-right: .5em; border-right: 1px solid #d8d8d8; } -.highlight.pygments .lineno { display: inline-block; margin-right: .25em; } -table.pyhltable .linenodiv { background-color: transparent !important; padding-right: 0 !important; } -.quoteblock { margin: 0 0 1.25em 0; padding: 0.5625em 1.25em 0 1.1875em; border-left: 3px solid #487c58; } -.quoteblock blockquote { margin: 0 0 1.25em 0; padding: 0 0 0.625em 0; border: 0; } -.quoteblock blockquote > .paragraph:last-child p { margin-bottom: 0; } -.quoteblock .attribution { margin-top: -0.625em; padding-bottom: 0.625em; font-size: inherit; color: #454545; line-height: 1.6; } -.quoteblock .attribution br { display: none; } -.quoteblock .attribution cite { display: block; } -table.tableblock { max-width: 100%; } -table.tableblock td .paragraph:last-child p > p:last-child, table.tableblock th > p:last-child, table.tableblock td > p:last-child { margin-bottom: 0; } -table.spread { width: 100%; } -table.tableblock, th.tableblock, td.tableblock { border: 0 solid #dddddd; } -table.grid-all th.tableblock, table.grid-all td.tableblock { border-width: 0 1px 1px 0; } -table.grid-all tfoot > tr > th.tableblock, table.grid-all tfoot > tr > td.tableblock { border-width: 1px 1px 0 0; } -table.grid-cols th.tableblock, table.grid-cols td.tableblock { border-width: 0 1px 0 0; } -table.grid-all * > tr > .tableblock:last-child, table.grid-cols * > tr > .tableblock:last-child { border-right-width: 0; } -table.grid-rows th.tableblock, table.grid-rows td.tableblock { border-width: 0 0 1px 0; } -table.grid-all tbody > tr:last-child > th.tableblock, table.grid-all tbody > tr:last-child > td.tableblock, table.grid-all thead:last-child > tr > th.tableblock, table.grid-rows tbody > tr:last-child > th.tableblock, table.grid-rows tbody > tr:last-child > td.tableblock, table.grid-rows thead:last-child > tr > th.tableblock { border-bottom-width: 0; } -table.grid-rows tfoot > tr > th.tableblock, table.grid-rows tfoot > tr > td.tableblock { border-width: 1px 0 0 0; } -table.frame-all { border-width: 1px; } -table.frame-sides { border-width: 0 1px; } -table.frame-topbot { border-width: 1px 0; } -th.halign-left, td.halign-left { text-align: left; } -th.halign-right, td.halign-right { text-align: right; } -th.halign-center, td.halign-center { text-align: center; } -th.valign-top, td.valign-top { vertical-align: top; } -th.valign-bottom, td.valign-bottom { vertical-align: bottom; } -th.valign-middle, td.valign-middle { vertical-align: middle; } -table thead th, table tfoot th { font-weight: bold; } -tbody tr th { display: table-cell; line-height: 1.6; background: whitesmoke; } -tbody tr th, tbody tr th p, tfoot tr th, tfoot tr th p { color: #333333; font-weight: bold; } -td > div.verse { white-space: pre; } -ul.unstyled, ol.unnumbered, ul.checklist, ul.none { list-style-type: none; } -ul.unstyled, ol.unnumbered, ul.checklist { margin-left: 0.625em; } -ul.checklist li > p:first-child > .fa-check-square-o:first-child, ul.checklist li > p:first-child > input[type="checkbox"]:first-child { margin-right: 0.25em; } -ul.checklist li > p:first-child > input[type="checkbox"]:first-child { position: relative; top: 1px; } -ul.inline { margin: 0 auto 0.625em auto; margin-left: -1.375em; margin-right: 0; padding: 0; list-style: none; overflow: hidden; } -ul.inline > li { list-style: none; float: left; margin-left: 1.375em; display: block; } -ul.inline > li > * { display: block; } -.unstyled dl dt { font-weight: normal; font-style: normal; } -ol.arabic { list-style-type: decimal; } -ol.decimal { list-style-type: decimal-leading-zero; } -ol.loweralpha { list-style-type: lower-alpha; } -ol.upperalpha { list-style-type: upper-alpha; } -ol.lowerroman { list-style-type: lower-roman; } -ol.upperroman { list-style-type: upper-roman; } -ol.lowergreek { list-style-type: lower-greek; } -.hdlist > table, .colist > table { border: 0; background: none; } -.hdlist > table > tbody > tr, .colist > table > tbody > tr { background: none; } -td.hdlist1 { padding-right: .75em; font-weight: bold; } -td.hdlist1, td.hdlist2 { vertical-align: top; } -.literalblock + .colist, .listingblock + .colist { margin-top: -0.5em; } -.colist > table tr > td:first-of-type { padding: 0 .75em; line-height: 1; } -.colist > table tr > td:last-of-type { padding: 0.25em 0; } -.qanda > ol > li > p > em:only-child { color: #1d4b8f; } -.thumb, .th { line-height: 0; display: inline-block; border: solid 4px white; -webkit-box-shadow: 0 0 0 1px #dddddd; box-shadow: 0 0 0 1px #dddddd; } -.imageblock.left, .imageblock[style*="float: left"] { margin: 0.25em 0.625em 1.25em 0; } -.imageblock.right, .imageblock[style*="float: right"] { margin: 0.25em 0 1.25em 0.625em; } -.imageblock > .title { margin-bottom: 0; } -.imageblock.thumb, .imageblock.th { border-width: 6px; } -.imageblock.thumb > .title, .imageblock.th > .title { padding: 0 0.125em; } -.image.left, .image.right { margin-top: 0.25em; margin-bottom: 0.25em; display: inline-block; line-height: 0; } -.image.left { margin-right: 0.625em; } -.image.right { margin-left: 0.625em; } -a.image { text-decoration: none; } -span.footnote, span.footnoteref { vertical-align: super; font-size: 0.875em; } -span.footnote a, span.footnoteref a { text-decoration: none; } -span.footnote a:active, span.footnoteref a:active { text-decoration: underline; } -#footnotes { padding-top: 0.75em; padding-bottom: 0.75em; margin-bottom: 0.625em; } -#footnotes hr { width: 20%; min-width: 6.25em; margin: -.25em 0 .75em 0; border-width: 1px 0 0 0; } -#footnotes .footnote { padding: 0 0.375em; line-height: 1.3; font-size: 0.875em; margin-left: 1.2em; text-indent: -1.2em; margin-bottom: .2em; } -#footnotes .footnote a:first-of-type { font-weight: bold; text-decoration: none; } -#footnotes .footnote:last-of-type { margin-bottom: 0; } -#content #footnotes { margin-top: -0.625em; margin-bottom: 0; padding: 0.75em 0; } -.gist .file-data > table { border: none; background: #fff; width: 100%; margin-bottom: 0; } -.gist .file-data > table td.line-data { width: 99%; } -div.unbreakable { page-break-inside: avoid; } -.replaceable { font-style: italic; font-color: inherit; font-family: inherit; } -.parameter { font-style: italic; font-family: monospace; } -.userinput { font-weight: bold; font-family: monospace; } -.envar { font-weight: bold; font-family: monospace; font-size: 90%; } -.sysitem { font-weight: bold; font-size: 90%; } -.package { font-weight: bold; font-size: 90%; } -.filename { font-weight: bold; font-style: italic; font-size: 90%; } -.big { font-size: larger; } -.small { font-size: smaller; } -.underline { text-decoration: underline; } -.overline { text-decoration: overline; } -.line-through { text-decoration: line-through; } -.aqua { color: #00bfbf; } -.aqua-background { background-color: #00fafa; } -.black { color: black; } -.black-background { background-color: black; } -.blue { color: #0000bf; } -.blue-background { background-color: #0000fa; } -.fuchsia { color: #bf00bf; } -.fuchsia-background { background-color: #fa00fa; } -.gray { color: #606060; } -.gray-background { background-color: #7d7d7d; } -.green { color: #006000; } -.green-background { background-color: #007d00; } -.lime { color: #00bf00; } -.lime-background { background-color: #00fa00; } -.maroon { color: #600000; } -.maroon-background { background-color: #7d0000; } -.navy { color: #000060; } -.navy-background { background-color: #00007d; } -.olive { color: #606000; } -.olive-background { background-color: #7d7d00; } -.purple { color: #600060; } -.purple-background { background-color: #7d007d; } -.red { color: #bf0000; } -.red-background { background-color: #fa0000; } -.silver { color: #909090; } -.silver-background { background-color: #bcbcbc; } -.teal { color: #006060; } -.teal-background { background-color: #007d7d; } -.white { color: #bfbfbf; } -.white-background { background-color: #fafafa; } -.yellow { color: #bfbf00; } -.yellow-background { background-color: #fafa00; } -span.icon > .fa { cursor: default; } -.admonitionblock td.icon [class^="fa icon-"] { font-size: 2.5em; cursor: default; } -.admonitionblock td.icon .icon-note:before { content: "\f05a"; color: #4E9FDD; } -.admonitionblock td.icon .icon-tip:before { content: "\f0eb"; color: #2C8596; } -.admonitionblock td.icon .icon-warning:before { content: "\f071"; color: #ec7a08; } -.admonitionblock td.icon .icon-caution:before { content: "\f06d"; color: #ec7a08; } -.admonitionblock td.icon .icon-important:before { content: "\f06a"; color: #c00; } -.conum[data-value] { display: inline-block; color: white !important; background-color: #333333; -webkit-border-radius: 100px; border-radius: 100px; text-align: center; width: 20px; height: 20px; font-size: 12px; line-height: 20px; font-family: "Open Sans", "Sans", sans-serif; font-style: normal; font-weight: bold; text-indent: -1px; } -.conum[data-value] * { color: white !important; } -.conum[data-value] + b { display: none; } -.conum[data-value]:after { content: attr(data-value); } -pre .conum[data-value] { position: relative; top: -2px; } -b.conum * { color: inherit !important; } -.conum:not([data-value]):empty { display: none; } -.print-only { display: none !important; } -@media print { @page { margin: 1.25cm 0.75cm; } - * { -webkit-box-shadow: none !important; box-shadow: none !important; text-shadow: none !important; } - a, a:visited { color: inherit !important; text-decoration: underline !important; } - a[href^="http:"]:after, a[href^="https:"]:after { content: " (" attr(href) ")"; } - a[href^="#"], a[href^="#"]:visited, a[href^="mailto:"], a[href^="mailto:"]:visited { text-decoration: none !important; } - abbr[title]:after { content: " (" attr(title) ")"; } - pre, blockquote { page-break-inside: avoid; } - code { color: #191919; } - thead { display: table-header-group; } - tr, img { page-break-inside: avoid; } - img { max-width: 100% !important; } - p { orphans: 3; widows: 3; } - h2, h3, #toctitle, .sidebarblock > .content > .title, #toctitle, .sidebarblock > .content > .title { page-break-after: avoid; } - #toc, .sidebarblock { background: none !important; } - #toc { border-bottom: 1px solid #d8d8d8 !important; padding-bottom: 0 !important; } - .sect1 { padding-bottom: 0 !important; } - .sect1 + .sect1 { border: none !important; } - body.book #header { text-align: center; } - body.book #header > h1 { border: none !important; margin: 2.5em 0 1em 0; padding: 0; } - body.book #header span { line-height: 1.6; } - body.book #header br { display: block; } - body.book #header br + span { padding-left: 0; } - body.book #header br + span:before { content: none !important; } - body.book #toc { border: none !important; text-align: left !important; padding: 0 !important; } - #footer { background: none !important; } - #footer-text { color: #333333 !important; } - .hide-on-print { display: none !important; } - .print-only { display: block !important; } - .hide-for-print { display: none !important; } - .show-for-print { display: inherit !important; } } - -.corner-ribbon{ - width: 16em; - background: #3c6eb4 ; - position: absolute; - top: 3em; - right: -4em; - text-align: center; - line-height: 5ex; - color: #dedede; - transform: rotate(45deg); - -webkit-transform: rotate(45deg); - z-index: 999; -} -.corner-ribbon a { color: #FFFFFF; } diff --git a/_templates/_breadcrumb.html.erb b/_templates/_breadcrumb.html.erb deleted file mode 100644 index 70a9e5e..0000000 --- a/_templates/_breadcrumb.html.erb +++ /dev/null @@ -1,14 +0,0 @@ -<%- 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/_css.html.erb b/_templates/_css.html.erb deleted file mode 100644 index 0fca7ae..0000000 --- a/_templates/_css.html.erb +++ /dev/null @@ -1,3 +0,0 @@ -<%- Dir.glob("_stylesheets/*").sort.each do |sheet| -%> - -<%- end -%> diff --git a/_templates/_nav.html.erb b/_templates/_nav.html.erb deleted file mode 100644 index b622156..0000000 --- a/_templates/_nav.html.erb +++ /dev/null @@ -1,18 +0,0 @@ -<%- navigation.each do |topic_group| -%> - <%- if not topic_group.has_key?(:topics) -%> - <%- if topic_id == topic_group[:id] %> -
  • <%= topic_group[:name] %>
    • - <%- else %> -
  • <%= topic_group[:name] %>
    • - <%- end %> - <%- else -%> -
  • - -  <%= topic_group[:name] %> - -
      - <%= render("_templates/_nav.html.erb", :navigation => topic_group[:topics], :topic_id => topic_id, :subtopic_shim => subtopic_shim) %> -
    -
    • - <%- end -%> -<%- end -%> diff --git a/_templates/_title.html.erb b/_templates/_title.html.erb deleted file mode 100644 index ff3eaa8..0000000 --- a/_templates/_title.html.erb +++ /dev/null @@ -1,8 +0,0 @@ -<%- 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 deleted file mode 100644 index c8f0018..0000000 --- a/_templates/page.html.erb +++ /dev/null @@ -1,150 +0,0 @@ - - - - - - - <%= distro %> <%= version %> | <%= [group_title, subgroup_title, topic_title].compact.join(' | ') %> - - - - - - - <%= render("_templates/_css.html.erb", :css_path => css_path) %> - - - - - - " rel="shortcut icon" type="text/css"> - - - - - <%- if version == "Rawhide" %> -
    ">Improve this Page
    - <%- end %> - -
    -
    -
    -
    - <%= render("_templates/_nav.html.erb", :navigation => navigation, :group_id => group_id, :topic_id => topic_id, :subgroup_id => subgroup_id, :subtopic_shim => subtopic_shim) %> -
    -
    -
    -

    <%= article_title %>

    -
    - <%= content %> -
    -
    -
    -
    -
    -
    -
    -
    -
    -

    About

    -
    -
    -
    Get Fedora
    -
    Sponsors
    -
    Fedora Magazine
    -
    Legal
    -
    -
    -
    - -
    -

    Support

    -
    -
    -
    Get Help
    -
    Ask Fedora
    -
    Common Bugs
    -
    Fedora Developer Portal
    -
    -
    -
    - -
    -

    Community

    -
    -
    -
    Join Fedora
    -
    About Fedora
    -
    Planet Fedora
    -
    Fedora Account System
    -
    -
    -
    -
    - - - -

    - © 2018 Red Hat, Inc. and others.
    Please send any comments or corrections - to the documentation team -

    -

    - Fedora is sponsored by Red Hat.
    - Learn more about the relationship between Red Hat and Fedora » -

    -
    - " alt="Red Hat Logo" /> -
    -
    -
    -
    -
    - - - - - - - diff --git a/_topic_map.yml b/_topic_map.yml deleted file mode 100644 index 4030d7f..0000000 --- a/_topic_map.yml +++ /dev/null @@ -1,75 +0,0 @@ -# This configuration file dictates the organization of the topic groups and -# topics on the main page of the doc site for this branch. Each record -# consists of the following: -# -# --- <= Record delimiter -# Name: Origin of the Species <= Display name of topic group -# Dir: origin_of_the_species <= Directory name of topic group -# Topics: -# - Name: The Majestic Marmoset <= Topic name -# File: the_majestic_marmoset <= Topic file under group dir +/- -# - Name: The Curious Crocodile <= Topic 2 name -# File: the_curious_crocodile <= Topic 2 file -# - Name: The Numerous Nematodes <= Sub-topic group name -# Dir: the_numerous_nematodes <= Sub-topic group dir -# Topics: -# - Name: The Wily Worm <= Sub-topic name -# File: the_wily_worm <= Sub-topic file under / -# - Name: The Acrobatic Ascarid <= Sub-topic 2 name -# File: the_acrobatic_ascarid <= Sub-topic 2 file under / -# -# The ordering of the records in this document determines the ordering of the -# topic groups and topics on the main page. ---- -Name: Fedora Modularity -Dir: en-US -Topics: - - Name: Fedora Modularity - File: index - - Name: How does it work - Dir: architecture - Topics: - - Name: How does it work - File: Main_Concepts - - Name: Building Software - Dir: building-software - Topics: - - Name: Building Software - File: Building_Software - - Name: Naming modules - File: Naming_and_organizing_modules - - Name: Consuming Software - Dir: consuming-software - Topics: - - Name: Consuming Software - File: Consuming_Software - - Name: DNF Behavior - File: Modular_DNF_Behavior - - Name: Making Modules - Dir: making-modules - Topics: - - Name: Adding New Modules - File: adding-new-modules - - Name: Updating Modules - File: updating-modules - - Name: Inspecting Build Failures - File: inspecting-build-failures - - Name: Building Modules Locally - File: building-modules-locally - - Name: Defining Modules in modulemd - File: Defining_Modules_in_Modulemd - - Name: Managing Defaults - File: managing-defaults - - Name: Using Modules - File: Using_Modules - - Name: Community - Dir: community - Topics: - - Name: Community - File: Communication - - Name: Teams and Working Groups - File: working_groups_and_teams - - Name: References - File: References - - Name: FAQ - File: FAQ diff --git a/antora.yml b/antora.yml new file mode 100644 index 0000000..a877c9a --- /dev/null +++ b/antora.yml @@ -0,0 +1,6 @@ +name: modularity +title: Modularity +version: master +start_page: ROOT:index +nav: +- modules/ROOT/nav.adoc diff --git a/build.sh b/build.sh new file mode 100755 index 0000000..c9349e3 --- /dev/null +++ b/build.sh @@ -0,0 +1,16 @@ +#!/bin/sh + +if [ "$(uname)" == "Darwin" ]; then + # Running on macOS. + # Let's assume that the user has the Docker CE installed + # which doesn't require a root password. + docker run --rm -it -v $(pwd):/antora antora/antora --html-url-extension-style=indexify site.yml + +elif [ "$(expr substr $(uname -s) 1 5)" == "Linux" ]; then + # Running on Linux. + # Let's assume that it's running the Docker deamon + # which requires root. + echo "" + echo "This build script is using Docker to run the build in an isolated environment. You might be asked for a root password in order to start it." +sudo docker run --rm -it -v $(pwd):/antora:z antora/antora --html-url-extension-style=indexify site.yml +fi diff --git a/en-US/FAQ.adoc b/en-US/FAQ.adoc deleted file mode 100644 index 2af6988..0000000 --- a/en-US/FAQ.adoc +++ /dev/null @@ -1,36 +0,0 @@ -= Frequently Asked Questions (FAQ) - -[qanda] -Exactly what problem are you trying to solve?:: - The “too fast vs. too slow” problem, outdated containers, and complex packaging workflow. - See The Problem to be Solved page for more detailed information. -How is this different from containers?:: - This is a build step that happens before containers. - Modularity provides parallel availability of multiple versions that can be consumed by containers to enable parallel installation. -How does this differ from Software Collections (SCLs)?:: - Modularity is about building multiple versions of packages, and making them all available to users. - SCLs are about installing software in parallel using RPM. - These two don’t overlap, they complement each other. You can build a Modular SCL. -Couldn’t we solve this with having compat- packages, or putting versions into package names for different version streams?:: - That works technically, but the packaging workload doesn’t scale, and dependency interactions become complex. This will let packagers make more content available to users without an explosion of effort. - Modules also help to solve the discoverability problem. - For example, is httpd v2.4 in a package called httpd-2-4 or http-2? -Can I install more versions at once?:: - Modularity does not invent a new technology for parallel installation. - Existing solution such as containers or Software Collections can be used to achieve this. -How is this different from RPM? Why not just different repos?:: - Technical: DNF performance with many repositories. We envision having tens or even hundreds of modules available to a single system. + - User experience: A repository is a source of software provided by a vendor, not necessarily representing a single application, language stack, or any other logical unit of software. - A repository typically contains multiple applications, stacks, etc. - We do not want to change this concept. -Are you going to produce all versions? What lifecycles and versions are envisioned?:: - We are developing the technology such as the build pipeline and client tooling to enable contributors to build multiple versions. - We envision longer lifecycles of stacks mainly for server, and devel/rolling releases of some stacks for developers. - However, contributors to the Fedora project will be the deciders and maintainers of any versions that are available. -I can just ‘dnf downgrade’ to get an older version.. Why do we need modularity?:: - Using an older version that is no longer maintained can be dangerous, mostly because of the lack of security updates. - Modules, on the other hand, represent a major version that is still being actively maintained by the upstream and therefore should receive updates. -Is this different from single app VMs with custom versions?:: - This helps with a single app VM with custom versions. - Same as with containers, it helps users to get the right version for their system. - diff --git a/en-US/References.adoc b/en-US/References.adoc deleted file mode 100644 index 98f7eae..0000000 --- a/en-US/References.adoc +++ /dev/null @@ -1,19 +0,0 @@ -= References - -https://pagure.io/modulemd[Module metadata definitions (modulemd)]:: - A modulemd file is used to define a module, and also to provide metadata for the end result. This is a specification of the file. - We are currently on version 1 of the specification with version 2 due very soon. - -https://pagure.io/modularity/issues[General issue tracker for Modularity]:: - General issues that are tracked here. - -https://pagure.io/group/modularity[Modularity on Pagure]:: - Pagure is the default place for most of our git repositories. - -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/Using_Modules.adoc b/en-US/Using_Modules.adoc deleted file mode 100644 index 41c9876..0000000 --- a/en-US/Using_Modules.adoc +++ /dev/null @@ -1,62 +0,0 @@ -= Using Modules in Fedora - -++++ - -++++ - -From the user perspective, modules are like release-independent package groups on independent lifecycles, providing alternative streams of content to Fedora. - -== Enable modular repositories - -If you are running the Fedora Server Edition, the Modular Repository should already be enabled. -However, if you are using a container or a different Edition, you need to: - - # dnf install fedora-repos-modular - -== Supported / Unsupported Package Managers - -* Supported -** dnf -** dnfdragora -* Unsupported (if unlisted, assume unsupported) -** microdnf -** PackageKit -** Gnome Software -** Apper -** Cockpit - -Using an unsupported Package Manager for *any* reason with modules enabled has serious potential to break things. -People are working on the above list of Unsupported package managers primarily by including module support in libdnf. -If you are interested in adding module support to a different package manager, please contact the https://github.com/rpm-software-management/dnf[dnf team]. - -== List available modules - -To list all available modules and their streams, run the following command: - - $ dnf module list - -== Install a module - -To install a module, use the `name:stream/profile` syntax, for example: - - $ dnf module install nodejs:6/default - -Alternatively, you can also enable a module and then install RPM packages directly: - - $ dnf module enable nodejs:6 - $ dnf install nodejs - -== Changing a stream - -To change a stream of a module that has been already installed, use the installation command. For example: - - $ dnf module install nodejs:9/default - -== Module defaults - -We are currently working on _system profiles_ — the defaults for your system. -Thanks to these, you will need to be specific about the module, stream, or profile only when you need to. When implemented, all the following commands will also work: - - $ dnf install nodejs # installs a nodejs RPM package from the default stream - $ dnf module install nodejs # installs the default profile from the default stream - $ dnf module install nodejs:9 # installs the default profile from the 9 stream diff --git a/en-US/architecture/Main_Concepts.adoc b/en-US/architecture/Main_Concepts.adoc deleted file mode 100644 index d861905..0000000 --- a/en-US/architecture/Main_Concepts.adoc +++ /dev/null @@ -1,71 +0,0 @@ -= Main Concepts of Modularity - -Modularity reuses some existing and creates some new concepts in the build and release process in Fedora. - -== Packages - -image::mod-doc-package.png[,80%,] - -We are reusing packages as they are. - -Packages are the smallest unit of software delivery. -Right now, Fedora uses RPM packages to build and ship all of its software. -There is a distinction between source RPM (SRPM) packages and binary RPM packages. - -As the name suggests, *source packages* contain the source code, but also the build process definition including a list of build dependencies. -Building a source package results in one or multiple binary packages. - -*Binary packages* are produced by building source packages in a build environment called a buildroot. -Different buildroots produce different binary packages. -This means that a source package without a context is not a complete definition of a resulting binary package. - -Every Fedora release has its own buildroot. -Even when multiple releases contain the same package using the same source, they are built multiple times, once in each buildroot, producing different (and often incompatible) binary packages. -Also, over time, as the distribution gets updated, so does its buildroot. -As a result, a package built today may not result in the same binary as a package built tomorrow. - -*Packages are either a part of a release, or a part a module.* - -== Releases - -image::mod-doc-release.png[,80%,] - -Releases are the generations of Fedora e.g. “Fedora 28”, “Fedora 29”, or “epel 7”. - -Each release can only contain one major version of every package (by policy). -In general, Fedora tends to ship the latest stable versions of software available. -At the same time, packages need to maintain a certain API/ABI stability throughout the lifecycle of the release they are part of. - -The problem with this approach is finding the right balance of being too fast vs. too slow. -For example, developers in general tend to prefer the newest versions of software, while server administrators want API/ABI stability for a longer period of time. -This problem is solved by Modules. - -== Modules and Streams - -image:mod-doc-module.png[,80%,] - -*Modules* are collections of packages representing a logical unit e.g. an application, a language stack, a set of tools. -These packages are built, tested, and released together. - -Each module defines its own lifecycle which is closer to the upstream rather than the Fedora release. - -Modules are the mechanism of delivering multiple streams (versions) of software for the same release. -This also works the other way round, the same stream for multiple releases. - -image::mod-doc-stream.png[,80%,] - -A *stream* is a series of versions having a goal such as backwards API/ABI compatibility or delivering the latest stable version. -A “nodejs” interpreter can have streams such as https://src.fedoraproject.org/modules/nodejs/branch/6[6] or https://src.fedoraproject.org/modules/nodejs/branch/8[8] (two current versions of nodejs), but also “devel” or “latest”. -Some packages don’t have a major version. -An example could be the “calc” package that is being developed in two branches “stable” and “unstable”. - -Simply put, streams are the mechanism of delivering and updating software at different speeds, allowing developers to have bleeding-edge software, and server admins longer stability. - -== Artifacts - -image::mod-doc-repositories.png[,80%,] - -Artifacts are consumable outputs of the build and release processes e.g. an iso image, an RPM repository, a container base image, or an ostree tree. - -Modules will be delivered as an RPM repository that will work on top of existing releases. -This repository will also be available in the Fedora container base image, enabling users to build containers with multiple versions of software. diff --git a/en-US/architecture/building-software/Building_Software.adoc b/en-US/architecture/building-software/Building_Software.adoc deleted file mode 100644 index bd6fc61..0000000 --- a/en-US/architecture/building-software/Building_Software.adoc +++ /dev/null @@ -1,55 +0,0 @@ -= Building Software with Modularity - -This is a high-level overview of how builds work with Fedora Modularity and how it compares with traditional builds. - -== Traditional package builds - -image::mod-doc-trad-builds.png[,80%,] - -In the existing Fedora world, packages are maintained in branches that map to specific Fedora releases. -Package repositories have branches e.g. “f27” for Fedora 27, “f28” for Fedora 28, etc. - -There are no changes to the existing packager workflow. -Maintaining release-specific branches and using the existing commands to build them keep working. - -== Modular package builds - -image::mod-doc-stream-builds.png[,80%,] - -Modularity changes package branching to be version-focused. - -Branching packages according to their major version as opposed to the distribution release brings more clarity — because we can see what lives in a branch, and removes source duplication — because there is one branch per version. - -While this approach makes more sense from the software perspective, there is no longer a clear mapping of a package branch to a particular release. -Modules are a way of defining this. - -== Building one source for multiple releases - -image::mod-doc-build-more-releases.png[,40%,] - -Modules define what package branches are built for which Fedora releases. -One module can be built for multiple releases. - -The above example produces three different binaries, one for each release. In case there are multiple architectures, three binaries will be produced (one each). - -== Building multiple versions - -image::mod-doc-build-more-versions.png[,40%,] - -Multiple versions of packages can be built for one release by defining multiple modules. -Users are able to choose which version they want to use on their system. - -The above example produces two different binaries, each with a different Python version. -Again, in case there are multiple architectures, two binaries will be produced for each one. - -Modularity also leverages existing technologies such as containers to enable users to run multiple versions at the same time on one "machine." - -== Building against multiple versions - -image::mod-doc-build-matrix.png[,60%,] - -Modules can be also be built against other modules to achieve more complex results. -Client tooling always makes sure the right version is installed for a given context. - -The above example produces two different binaries, each bound to a different Python version. -Again, in case there are multiple architectures, two binaries will be produced for each one. diff --git a/en-US/architecture/building-software/Naming_and_organizing_modules.adoc b/en-US/architecture/building-software/Naming_and_organizing_modules.adoc deleted file mode 100644 index efcfd7f..0000000 --- a/en-US/architecture/building-software/Naming_and_organizing_modules.adoc +++ /dev/null @@ -1,59 +0,0 @@ -= Naming and organizing modules - - -Modules are uniquely identified by NSVCA which stands for _name_, _stream_, _version_, _context_, and _architecture_. - -*When creating a new module*, you only need to decide about the *name* (name of your module, such as _nodejs_), and the *stream* (the flavour of your module, mostly a major version, such as _8_). - -== Deep Dive - -If you want more details about the whole NSVCA, continue reading. - -=== Source level ID (NSV) - -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 (NSVCA) - -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/architecture/building-software/images/mod-doc-build-matrix.png b/en-US/architecture/building-software/images/mod-doc-build-matrix.png deleted file mode 100644 index 8f58a39..0000000 Binary files a/en-US/architecture/building-software/images/mod-doc-build-matrix.png and /dev/null differ diff --git a/en-US/architecture/building-software/images/mod-doc-build-more-releases.png b/en-US/architecture/building-software/images/mod-doc-build-more-releases.png deleted file mode 100644 index 63f7e92..0000000 Binary files a/en-US/architecture/building-software/images/mod-doc-build-more-releases.png and /dev/null differ diff --git a/en-US/architecture/building-software/images/mod-doc-build-more-versions.png b/en-US/architecture/building-software/images/mod-doc-build-more-versions.png deleted file mode 100644 index 0869c97..0000000 Binary files a/en-US/architecture/building-software/images/mod-doc-build-more-versions.png and /dev/null differ diff --git a/en-US/architecture/building-software/images/mod-doc-stream-builds.png b/en-US/architecture/building-software/images/mod-doc-stream-builds.png deleted file mode 100644 index 6896f32..0000000 Binary files a/en-US/architecture/building-software/images/mod-doc-stream-builds.png and /dev/null differ diff --git a/en-US/architecture/building-software/images/mod-doc-trad-builds.png b/en-US/architecture/building-software/images/mod-doc-trad-builds.png deleted file mode 100644 index d525e25..0000000 Binary files a/en-US/architecture/building-software/images/mod-doc-trad-builds.png and /dev/null differ diff --git a/en-US/architecture/consuming-software/Consuming_Software.adoc b/en-US/architecture/consuming-software/Consuming_Software.adoc deleted file mode 100644 index b027715..0000000 --- a/en-US/architecture/consuming-software/Consuming_Software.adoc +++ /dev/null @@ -1,61 +0,0 @@ -= Consuming Software with Modularity - -This is a high-level overview of how users can install software with Fedora Modularity and how is it different from the traditional workflow(s). - -== Understanding the Delivery Channels - -Modular Fedora will ship with two sets of repositories: - -. The *traditional base repository* representing the distribution as we know it today — there are no user-visible changes in this part. - -. A new *modular repository* (often referred to as the "Application Stream" or AppStream for short) including all the additional versions delivered as modules. - -The Modules repository will be optional for users. - -image::mod-doc-repositories.png[,80%,] - -== Consuming the traditional packages - -There are no changes to the traditional user experience. -Packages from the traditional repository will be installed and updated using the same methods as before. -Everything keeps working as it used to. - -== Consuming the modular packages - -If a user desires to use the optioanl Modular repositories in order to consume non-default versions of software, there will be some new concepts introduced in the client tooling to manage them. -We outline these below. - -=== Enabling a module - -Enabling a module makes its packages available on the system. -Packages delivered as part of a module always have a priority over the ones from the traditional base, regardless of their actual version. -Packages in modules are often replacements of the ones in the traditional base. - -Modularity brings parallel availability, not parallel installability. -Only one stream of a given module can be enabled on a system — so it is always clear which version gets installed. -Installing and running multiple versions of software can be achieved by using existing technologies, such as containers. - -=== Installing a module - -To make installation easy, some modules can be also installed as a unit, without the need of enabling them first and then installing individual packages. -Installing a module doesn’t necessarily mean installing all of its packages. -Modules can define something called an "installation profile" to help users with the installation. - -==== Installation profile - -Installation profiles are essentially lists of packages that help users with the module installation. To give a specific example, a database module could have two profiles: server and client. This helps the user to install what they need without the need of thinking about the package names. However, installation profiles are just an optional feature and users can still install packages directly. - -==== Updating the system - -Updating the system always respects user’s module choices (or lack of module) even when there are multiple (and possibly higher) versions available. - -If the user doesn’t enable any modules, all packages on their system get updated to the latest versions provided by the traditional base repository. -However, if the user enables a module stream, packages get updated to the newest version provided by the module. - -Thanks to this mechanism, the user has better control over the versions of packages on their system while receiving updates (such as security patches) for the whole system. - -==== Running multiple versions using containers - -Modularity brings parallel availability, not parallel installability. There are other technologies i.e. linux containers or software collections that deal with this. - -All the steps described above can be used in a container the same way as on a traditional system. Producing up-to-date containers with multiple versions of software in an automated way is also one of the goals. diff --git a/en-US/architecture/consuming-software/Modular_DNF_Behavior.adoc b/en-US/architecture/consuming-software/Modular_DNF_Behavior.adoc deleted file mode 100644 index c002d4e..0000000 --- a/en-US/architecture/consuming-software/Modular_DNF_Behavior.adoc +++ /dev/null @@ -1,142 +0,0 @@ -= Modular DNF Behavior - -This page captures the key behaviors of modular DNF. - -== Definitions - -* Ursine ("bare") packages are those that are not part of any module. -* A module's "context" is a unique hash value generated by the build - system to distinguish binaries built for different Fedora releases as - a result of stream expansion. - See <>. - -== General - -* Existing use of RPM-based operations must not change and must - continue to work just as they always have. -* DNF install/update commands can be invoked by using syntax of either - `dnf module $modspec ...` or `dnf @$modspec ...`. -* The "platform" pseudo-module cannot be explicitly enabled, installed, - deleted, or have its stream changed. -* A module is specified by its name, stream, version, context, and - architecture (eg., "module:stream:version:context:arch"). -** If a module has a default stream defined on a system, "stream" may be - omitted. Otherwise, "stream" must be explicitly provided. -** For a given "module:stream", "version" can always be omitted. If - "version" is not explicitly provided, the latest "version" for the - given "module:stream" will be chosen. -** If the module "context" is not specified, DNF will use heuristics to - determine the appropriate "context". - See <>. -** If the module "arch" is not specified, the system's base architecture - will be used. -** Specifying a non-existent "module" name should fail. -** Specifying a non-existent "stream" (for a valid "module") should fail. -** Specifying specifying a non-existent "version" - (for a valid "module:stream") should fail. -** Specifying specifying a non-existent "context" - (for a valid "module:stream:version") should fail. -** Specifying a non-existent "arch" - (for a valid "module:stream:version:context") should fail. - -== System modular defaults - -* DNF must look for modular default stream and installation profile - data in the repodata of the package installation repos--which is - sourced from <> during the Fedora build - and release process. -* DNF must look for _override_ data for modular default stream and - installation profile on the local system in - `/etc/dnf/modules.defaults.d/`. - -== Module listing - -* DNF must be able to list all modular content (modules, streams, - enabled streams, default streams, profiles, module packages, - profile packages). - -== Module enablement - -* Enabling a module stream makes all of its packages available on the - system, but does not install them. -* At most one stream of a module may be enabled at a time on a system. -* Enabling a different stream of a module must be confirmed by the user - (or "--assumeyes"). -* Enabling a different stream of a module will automatically disable - the old stream. - -== Module Auto-enablement - -* If an uninstalled/unenabled module has a valid default stream - configured, DNF will consider the default stream of the module and - all of its packages available for resolving dependencies--and will - automatically enable the default stream of that module if any packages - from it are installed directly or indirectly (to resolve dependencies). -* If an uninstalled/unenabled module:stream is listed as a runtime - dependency of another module being installed or enabled, DNF will - automatically enable that dependency. -* Once a particular stream of a module has been enabled, DNF may not - automatically enable a different stream. - -== Module/package installation - -* Installing a module enables the specified stream (or default stream, - if not specified) and installs all of the packages associated with the - specified profile (or "default" profile, if not specified). -* If a module does not explicitly have a "default" profile specified it - its modulemd, DNF must pretend that it exists and is empty. - See <>. -* Each profile of a module stream must be able to be installed. - However, a module's profiles may conflict amongst themselves such - that they cannot all be installed at the same time. - (A hypothetical example would be a module that provides something - analogous to the coreutils and coreutils-single packages in different - profiles. The coreutils packages provide the same functionality, but - conflict.) - -== Module update - -* Updating a module will update all installed packages that belong to - the enabled module stream--regardless if the packages were installed - by an install profile or ad-hoc. - -== Module disablement - -* Disabling a module does not remove any packages that belong to the - module. -* Disabling a module disables modules that depend on it--unless they - still have packages installed. - -== Module removal - -* Uninstalling a module removes all the packages that belong to the - module and disables it. -* Ad-hoc removal of all packages from an installed module does not - disable the module. - -== Module locking - -* A locked module cannot have a different stream enabled or be - disabled--without first unlocking it. - -== Stream expansion and contexts - -* Packages from module contexts that do not match the current - transaction are disregarded. - See <>. - -== Other - -* Any package in an enabled module takes priority over any ursine RPM - with the same package name, regardless of which repositories those - modules and packages may be in. -* If there's an ursine or modular RPM with a higher NVR than the hotfix - one, the ursine or modular one wins. This is to ensure new proper - updates override the temporary hotfix RPMs. - -[bibliography] -== References - -* [[[mmd-spec-v2]]] https://github.com/fedora-modularity/libmodulemd/blob/master/spec.v2.yaml -* [[[fedora-module-defaults-repo]]] https://pagure.io/releng/fedora-module-defaults -* [[[module-stream-expansion]]] https://fedoraproject.org/wiki/Infrastructure/Factory2/Focus/StreamExpansion diff --git a/en-US/architecture/consuming-software/images/mod-doc-repositories.png b/en-US/architecture/consuming-software/images/mod-doc-repositories.png deleted file mode 100644 index 734cbe8..0000000 Binary files a/en-US/architecture/consuming-software/images/mod-doc-repositories.png and /dev/null differ diff --git a/en-US/architecture/images/mod-doc-module.png b/en-US/architecture/images/mod-doc-module.png deleted file mode 100644 index a5a153c..0000000 Binary files a/en-US/architecture/images/mod-doc-module.png and /dev/null differ diff --git a/en-US/architecture/images/mod-doc-package.png b/en-US/architecture/images/mod-doc-package.png deleted file mode 100644 index 05e4223..0000000 Binary files a/en-US/architecture/images/mod-doc-package.png and /dev/null differ diff --git a/en-US/architecture/images/mod-doc-release.png b/en-US/architecture/images/mod-doc-release.png deleted file mode 100644 index 79f9d0d..0000000 Binary files a/en-US/architecture/images/mod-doc-release.png and /dev/null differ diff --git a/en-US/architecture/images/mod-doc-repositories.png b/en-US/architecture/images/mod-doc-repositories.png deleted file mode 100644 index 734cbe8..0000000 Binary files a/en-US/architecture/images/mod-doc-repositories.png and /dev/null differ diff --git a/en-US/architecture/images/mod-doc-stream.png b/en-US/architecture/images/mod-doc-stream.png deleted file mode 100644 index 029d74d..0000000 Binary files a/en-US/architecture/images/mod-doc-stream.png and /dev/null differ diff --git a/en-US/community/Communication.adoc b/en-US/community/Communication.adoc deleted file mode 100644 index 7d475db..0000000 --- a/en-US/community/Communication.adoc +++ /dev/null @@ -1,31 +0,0 @@ -= Communication - -This page lists the communication channels and meetings of members of the Modularity Working Group (Modularity WG). - - -== Channels - -There are two main communication channels the Modularity WG uses: - -:hash: # - -https://webchat.freenode.net/?channels=fedora-modularity[{hash}fedora-modularity] on freenode:: -Most of the discussions happen on this IRC channel. - -https://lists.fedoraproject.org/archives/list/devel@lists.fedoraproject.org/[devel@lists.fedoraproject.org]:: -The Modularity WG doesn't have a dedicated mailng list. -Instead, the Fedora Devel mailing list is used time to time for more complex decisions or announcements. - -https://lists.fedoraproject.org/archives/list/server@lists.fedoraproject.org/[server@lists.fedoraproject.org]:: -The https://fedoraproject.org/wiki/Server[Server SIG] also discusses Modularity at times as the Server Edition is a primary stakeholder in the goals of the https://fedoraproject.org/wiki/Objectives#Current[Modularity Objective]. - -== Meetings - -Meetings are listed on the https://apps.fedoraproject.org/calendar/modularity/[Modularity calendar]. -Currently, there are two alternating meetings on Tuesday: - -Modularity WG:: -A formal meeting of the Modularity WG to discuss, post updates, and make dedisions. - -Office Hours:: -No formal agenda, members of the Modularity WG promise to be present at this time for questions or discussion. diff --git a/en-US/community/working_groups_and_teams.adoc b/en-US/community/working_groups_and_teams.adoc deleted file mode 100644 index d3f6a1e..0000000 --- a/en-US/community/working_groups_and_teams.adoc +++ /dev/null @@ -1,9 +0,0 @@ -= 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/images/modularity-appstream-overview.png b/en-US/images/modularity-appstream-overview.png deleted file mode 100644 index c288149..0000000 Binary files a/en-US/images/modularity-appstream-overview.png and /dev/null differ diff --git a/en-US/images/modularity-building-modules.png b/en-US/images/modularity-building-modules.png deleted file mode 100644 index ae6dbcd..0000000 Binary files a/en-US/images/modularity-building-modules.png and /dev/null differ diff --git a/en-US/images/modularity-building-trad.png b/en-US/images/modularity-building-trad.png deleted file mode 100644 index 5e5e89f..0000000 Binary files a/en-US/images/modularity-building-trad.png and /dev/null differ diff --git a/en-US/index.adoc b/en-US/index.adoc deleted file mode 100644 index 4277104..0000000 --- a/en-US/index.adoc +++ /dev/null @@ -1,53 +0,0 @@ -= What is Modularity - -Modularity introduces a new optional repository to Fedora called Modular (often referred to as the "Application Stream" or AppStream for short) that ships additional versions of software on independent lifecycles. -This way users can keep their operating system up-to-date while having the right version of an application for their use case, even when the default version in the distribution changes. - -image::modularity-appstream-overview.png[,100%,] - - -== What Problems does Modularity Solve? - -=== Too fast vs. too slow - -Different users have different needs. -Developers want the latest versions possible, system administrators want stability for longer period of time. -There are many Linux distributions out there, each targetting a different audience, for example Fedora vs CentOS. - -Fedora generally ships the latest stable versions of its component packages when it is released twice per year. -That is convenient for desktop users and developers. -Even though many people use Fedora on a server, it is sometimes necessary to have a stable version of certain packages for a longer time, mostly because of third-party applications. - -At the same time, some people consider Fedora to be moving too slowly for them and want even newer runtimes on their system. -Some upstreams release their software faster than twice a year. - -On the other hand, CentOS targets long-term stability and releases a new version once every few years. -This is convenient for server admins as there are fewer changes over longer periods of time. -But some of the software gets old for modern applications and newer versions of runtimes might be needed. - -In other words, it would be convenient to be able to choose some parts of the system to be moving slowly, and other parts to be moving faster. -Can we do that? - -https://example.com[YES!] - -=== Outdated containers - -There are many containers out there. -The majority of them are built manually, not actively maintained, not patched with security fixes, and still used by many people. -This is especially true for the ones using software of a different version than the distribution their are based on provides. - -If Fedora had multiple versions of software that is actively maintained and built, could we use it to produce containers? -Could these containers get automatically rebuilt every time the packages get updated? - -https://example.com[YES!] - -=== Complex packager workflows - -Fedora contributors maintain their packages in multiple branches — one for each release. -Even when the packages are the same. -Leading to a series of manual steps associated with the build process. - -Could we enable packagers to maintain packages in branches that would follow the package version instead of an arbitrary distribution release version? -Having a single branch that builds across multiple releases would save some work for packagers. - -https://example.com[YES!] diff --git a/en-US/making-modules/Defining_Modules_in_Modulemd.adoc b/en-US/making-modules/Defining_Modules_in_Modulemd.adoc deleted file mode 100644 index aa3c946..0000000 --- a/en-US/making-modules/Defining_Modules_in_Modulemd.adoc +++ /dev/null @@ -1,369 +0,0 @@ -= Defining modules in modulemd - -Modules are defined using a https://pagure.io/modulemd[modulemd file]. The definition includes the summary and description, list of source RPM packages, build information i.e. buildroot, and usage information i.e. installation profiles or licenses. - -This page will help you with writing a module definition from scratch. Even though this page is meant to be up-to-date, please make sure your module complies with the https://fedoraproject.org/wiki/Module:Guidelines[Fedora Packaging Guidelines for Modules] as it is the authoritative point of truth. - -This page includes the <>, the <>, examples of <>, and a <>. - -== Common definitions - -Every modulemd starts with these three lines: - -[source,yaml] ----- -document: modulemd -version: 2 -data: - ... <1> ----- - -<1> All the following definitions go here, under _data_. - -=== Information about your module - -Tell users what this module represents by writing a summary and a description, and how can they use it by specifying a license. - -[source,yaml] ----- - summary: An example module - description: >- <1> - A module for the demonstration of the metadata format. Also, - the obligatory lorem ipsum dolor sit amet goes right here. - license: - module: - - MIT <2> ----- - -<1> The `>-` means new line in YAML. Useful for longer blocks of text, such as the description! - -<2> A license for this modulemd file. Fedora content, such as SPEC files or patches not included upstream, uses the MIT license by default, unless the component packager declares otherwise. - - -=== List the packages - -To make your module useful, include some RPM packages in it. List all source RPM packages this module should include. - -[source,yaml] ----- - components: - rpms: - first-package: <1> - rationale: Provides the core functionality. <2> - ref: 3.0 <3> - second-package: - rationale: Web UI for the first-package. - ref: stable - ... <4> ----- - -<1> Name of the package — maps to a DistGit repository name. - -<2> The reason why is this package here. Mostly for humans. - -<3> DistGit branch, tag, or a commit — so the right version of the package gets included. - -<4> List as many packages as you need. - -=== For which releases? - -To build your module for all Fedora releases that are actively maintained, use the following definition. For anything more than this, such as building against other modules or requiring other modules during runtime, please see the Advanced section below. - -[source,yaml] ----- - dependencies: - - buildrequires: - platform: [] - requires: - platform: [] ----- - -=== Help users install it (optional, but encouraged) - -To help users install your module, define installation profiles. These profiles represent a specific use case of your module. Most modules have at least a default profile. But you can specify more. For example, a database module can have a server and a client profile. - -[source,yaml] ----- - profiles: - default: <1> - description: A standard installation. <2> - rpms: - - package-one <3> - - package-one-extras <3> - - package-two <3> - cli: - description: A command-line client. - rpms: - - package-one-cli - ... <4> ----- - -<1> Name of the profile. - -<2> A quick summary of the profile. - -<3> Binary packages to be installed with this profile. - -<4> List as many profiles as you need. - -=== Public API (optional, but encouraged) - -List all binary RPM packages in your module that you consider to be the main stable feature of the module. Other (unlisted) packages should be considered unsupported, or an implementation detail. - -[source,yaml] ----- - api: - rpms: - - package-one - - package-one-extras - - package-one-cli - - package-one-devel - - package-two ----- - -== Advanced definitions - -=== References to the upstream (optional) - -You can also provide references to the upstream community, documentation, or to an issue tracker. - -[source,yaml] ----- - references: - community: http://www.example.com/ <1> - documentation: http://www.example.com/ <2> - tracker: http://www.example.com/ <3> ----- - -<1> Upstream community website, if it exists. - -<2> Upstream documentation, if it exists. - -<3> Upstream bug tracker, if it exists. - -=== Building in a specific order (optional) - -Packages are built in batches. By default, all packages are part of a single group, and therefore built concurently. - -To build packages in a specific order, assign them to multiple build groups. Build groups are identified by an integer. Groups with lower number are built first. Negative values are allowed, `0` is the implicit default value. - -In this specific example, `first-package` gets built first, and `second-package` gets built second. - -[source,yaml] ----- - components: - rpms: - first-package: - rationale: Provides the core functionality. - ref: 3.0 - buildorder: 0 <1> - second-package: - rationale: Web UI for the first-package. - ref: stable - buildorder: 10 <1> ----- - -<1> A number of the build group. - -=== Build macros (optional) - -Use this if you need to build your packages with a specific RPM macro. Applies to all packages in the module. - -[source,yaml] ----- - buildopts: - rpms: - macros: | - %demomacro 1 - %demomacro2 %{demomacro}23 ----- - -=== Advanced dependencies (optional) - -modules can be - -* built against other modules -* require other modules during runtime -* built agains one or more streams of the same module -* work with one or more streams of another module - - -==== Building for a specific Fedora release(s) only - -Building **only for Fedora 28**: - -[source,yaml] ----- - dependencies: - - buildrequires: - platform: [f28] - requires: - platform: [f28] ----- - -Building **for everything else than Fedora 28**: - -[source,yaml] ----- - dependencies: - - buildrequires: - platform: [-f28] - requires: - platform: [-f28] ----- - -Building **only for Fedora 28 and Fedora 29**: - -[source,yaml] ----- - dependencies: - - buildrequires: - platform: [f28, f29] - requires: - platform: [f28, f29] ----- - -==== Depending on other modules - -Your module can also depend on another modules. Specific streams can be referenced the same way as above in "Building for a specific Fedora release(s) only". - -[source,yaml] ----- - dependencies: - - buildrequires: - platform: [] - nodejs: [] - requires: - platform: [] - nodejs: [] ----- - -==== Complex dependencies - -Simple things should simple, complex things should be possible. Let's say my module requires `nodejs` during build and run time. It also requires `build-tools` only during build. To make it even more complex, it also requires a specific stream of a `pizza-module` during build and run time, but only on Fedora 27. - -[source,yaml] ----- - dependencies: - - buildrequires: - platform: [-f27] - buildtools: [v1, v2] - nodejs: [] - requires: - platform: [-f27] - nodejs: [] - - buildrequires: - platform: [f27] - buildtools: [v1, v2] - nodejs: [] - pizza-module: [3.6] - requires: - platform: [f27] - nodejs: [] - pizza-module: [3.6] ----- - -For even more complex scenarios, please study the https://github.com/fedora-modularity/libmodulemd/blob/master/spec.v2.yaml[modulemd specification]. - - -=== Binary packages to exclude (optional) - -One source RPM package might produce multiple binary RPM packages. If you don't want to include some binary packages, list them under `filter`. - -[source,yaml] ----- - filter: - rpms: - - first-package-debuginfo - - second-package-nope ----- - -== A minimal modulemd - -=== An absolute minimum - -This module includes two source RPM packages built for all Fedora releases. - -[source,yaml] ----- -document: modulemd -version: 2 -data: - summary: An example module - description: >- - A module for the demonstration of the metadata format. Also, - the obligatory lorem ipsum dolor sit amet goes right here. - license: - module: - - MIT - dependencies: - - buildrequires: - platform: [] - requires: - platform: [] - components: - rpms: - first-package: - rationale: Provides the core functionality. - ref: 3.0 - second-package: - rationale: Web UI for the first-package. - ref: stable ----- - -=== Including profiles and API (recommended) - -This module includes two source RPM packages built for all Fedora releases. It makes clear which packages are considered the API, and helps users with installation thanks to the profiles. - -[source,yaml] ----- -document: modulemd -version: 2 -data: - summary: An example module - description: >- - A module for the demonstration of the metadata format. Also, - the obligatory lorem ipsum dolor sit amet goes right here. - license: - module: - - MIT - dependencies: - - buildrequires: - platform: [] - requires: - platform: [] - api: - rpms: - - package-one - - package-one-extras - - package-one-cli - - package-one-devel - - package-two - profiles: - default: - description: A standard installation. - rpms: - - package-one - - package-one-extras - - package-two - cli: - description: A command-line client. - rpms: - - package-one-cli - components: - rpms: - first-package: - rationale: Provides the core functionality. - ref: 3.0 - second-package: - rationale: Web UI for the first-package. - ref: stable ----- - -=== Bonus: Converting modulemd v1 to v2 - -This video walks through the differences between the legacy modulemd v1 and the current modulemd v2. - -++++ - -++++ \ No newline at end of file diff --git a/en-US/making-modules/adding-new-modules.adoc b/en-US/making-modules/adding-new-modules.adoc deleted file mode 100644 index 58658a6..0000000 --- a/en-US/making-modules/adding-new-modules.adoc +++ /dev/null @@ -1,131 +0,0 @@ -= Adding new modules to Fedora - -This section will guide you through the whole process of adding a new module to Fedora. There is also an official https://fedoraproject.org/wiki/Modularity/Adding_New_Modules_and_Managing_Defaults[process for adding new modules] which will give you a summary of the major steps you need to undergo, and is the authoritative point of truth. - -== Step 1: Get your RPM packages in place - -**Goal**: Get your RPM package(s) pushed into the Fedora Distribution Git (dist-git). - -=== Workflow Summary: - -1. Create your new RPM package. -2. Submit your package for Fedora Review. -3. Request a new repository and a branch in dist-git. -4. Push your package sources into dist-git. - -=== Details: - -When creating your new http://rpm.org/[RPM package], please make sure it complies with the https://fedoraproject.org/wiki/Packaging:Guidelines[Fedora Packaging Guidelines]. - -To learn about the Fedora review, requesting repositories and branches, and pushing sources to dist-git, please see the https://fedoraproject.org/wiki/Package_Review_Process#Contributor[Fedora Package Review Process] - -== Step 2: Get your module definition in place - -**Goal**: Get your module definition pushed into the Fedora Distribution Git (dist-git). - -=== Steps: - -1. Write a modulemd. -2. Request a new repository and a branch in dist-git. -3. Push your modulemd into dist-git. - -=== Details: - -Writing a modulemd is covered in detail in the Defining Modules in modulemd section. - -NOTE: Running the following `fedpkg` commands requires a ticket to be created at https://pagure.io/settings/token/new and saved in `\~/.config/rpkg/fedpkg.conf` - -WARNING: Please remember that the name of your module will be the name of your repository. The same way, the stream name of your module will be the name of the branch. Both of these will be visible to users. - -To request a new repository in dist-git, for example for a `nodejs` module, run: - ----- -$ fedpkg --module-name modules/nodejs request-repo --exception ----- - -And to request a new branch, for example for a `nodejs:10` module, run: - ----- -$ fedpkg --module-name modules/nodejs request-branch 10 ----- - -To push your modulemd into dist-git, clone the dist-git repository, change to the correct branch, add your modulemd, and push it as you would in git. - -NOTE: Please make sure that the name of your modulemd file matches the name of the dist-git repository. - -For example, to push the `nodejs:10` module definition, run: - ----- -$ fedpkg clone modules/nodejs -$ cd nodejs -$ git checkout 10 -$ vim nodejs.yaml -$ git add nodejs.yaml -$ git commit -m "add the initial modulemd" -$ git push ----- - -== Step 3: Build your module - -**Goal**: Get your packages built as a module. - -=== Steps: - -1. Submit a module build using fedpkg. -2. Make sure your build succeeded. - -=== Details: - -Module builds are triggered using `fedpkg` from whithin your dist-git repository. - -For example, to submit a build of the `nodejs:10` module, run: - ----- -$ fedpkg clone modules/nodejs -$ cd nodejs -$ git checkout 10 -$ fedpkg module-build ----- - -NOTE: Please note the module build ID. You will need it to verify the build state. It also helps you in the next step. - -To watch the satate of your module build, run: - ----- -$ fedpkg module-build-watch BUILD_ID ----- - -When the module is in a "ready" state, you can continue to the next step. - - -== Step 4: Make your module available to users - -**Goal**: Make your module go through Bodhi — the Fedora updates system. - -=== Steps: - -1. Submit your module as an update in Bodhi. -2. Make sure your update has passed potential user testing. - -=== Details: - -To submit your module as an update, go to https://bodhi.fedoraproject.org/[Fedora Bodhi]. Make sure you are logged in, and then click on Create / New Update at the top-right corner. Fill out the following fields: - -* Candidate Builds: MODULE_BUILD_ID -* Update notes: notes for the users -* Final details: check what applies - -One way of geting the MODULE_BUILD_ID is running the same command as in the previous step: - ----- -$ fedpkg module-build-watch BUILD_ID ----- - -and changing the "koji tag" value in the following way: - ----- -module-nodejs-10-20180607142235-6c81f848 <- koji tag - nodejs-10-20180607142235.6c81f848 <- MODULE_BUILD_ID ----- - -that is removing the "module-" part at the beginning, and replacing the last "-" with a ".". \ 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 deleted file mode 100644 index 163ce7b..0000000 --- a/en-US/making-modules/building-modules-locally.adoc +++ /dev/null @@ -1,62 +0,0 @@ -= Building Fedora modules locally - -This page walks you through building modules locally on your machine. - -== Prerequisities - -You need to install the `module-build-service` as well as `fedpkg`: - ----- -$ sudo dnf install module-build-service fedpkg ----- - -and add yourself to the `mock` group: - ----- -$ sudo usermod -a -G mock USERNAME -$ newgrp ----- - -== Step 1: Build your module - -Local builds are started using `fedpkg` from whithin your dist-git repository. - -For example, to submit a build of the `testmodule:master` module, run: - ----- -$ fedpkg clone modules/nodejs -$ cd nodejs -$ git checkout master -$ fedpkg module-build-local ----- - -When the build finishes, you'll be able to find the results in: - ----- -~/modulebuild/builds/MODULE/results/ ----- - -where MODULE is "module-NAME-STREAM-VERSION", so for example "module-testmodule-master-20180612122805". - -== Step 2: Test your module - -WARNING: This requires Fedora 28 or higher. - -To test your module, add the repository to your system by creating an entry similar to this in `/etc/yum.repos.d/test.repo`: - ----- -[local] -name=My Local Repository -baseurl=file:///home/adam/modulebuild/builds/module-testmodule-master-20180612122805/results/ -gpgcheck=0 -enabled=1 ----- - -Please replace "adam" with your user name, and "module-testmodule-master-20180612122805" with the actual value for your module. - -Now, when you list the available modules on your system, you should be able to see it and install it: - ----- -$ dnf module list -$ dnf module install testmodule:master ----- \ No newline at end of file diff --git a/en-US/making-modules/inspecting-build-failures.adoc b/en-US/making-modules/inspecting-build-failures.adoc deleted file mode 100644 index 98c9962..0000000 --- a/en-US/making-modules/inspecting-build-failures.adoc +++ /dev/null @@ -1,47 +0,0 @@ -= Inspecting module build failures in Fedora - -Have you submitted a build which failed? This page will point you to the right places to get all the information about build failures. - -== Reminder: Building modules - -**Goal**: Get your packages built as a module. - -=== Steps: - -1. Submit a module build using fedpkg. -2. Make sure your build succeeded. - -=== Details: - -Module builds are triggered using `fedpkg` from whithin your dist-git repository. - -For example, to submit a build of the `nodejs:10` module, run: - ----- -$ fedpkg clone modules/nodejs -$ cd nodejs -$ git checkout 10 -$ fedpkg module-build ----- - -NOTE: Please note the module build ID. You will need it to verify the build state. It also helps you in the next step. - -To watch the satate of your module build, run: - ----- -$ fedpkg module-build-watch BUILD_ID ----- - -When the module is in a "ready" state, you can continue to the next step. - -However, in this scenario, we expect your build failed. - -== Inspecting build failures - -Run the following command using the BUILD_ID from the previous step: - ----- -$ fedpkg module-build-info BUILD_ID ----- - -which shows you "State Reason" — a short summary of the build failure regarding the whole module, as well as a list of individual packages in the module. Find the ones that failed and go to the "Koji Task" URL. There, click on the "Build" link which gets you to the module build page. On this page, inspect the `root.log`, `build.log`, and other files to get the build error. \ No newline at end of file diff --git a/en-US/making-modules/managing-defaults.adoc b/en-US/making-modules/managing-defaults.adoc deleted file mode 100644 index 173d83f..0000000 --- a/en-US/making-modules/managing-defaults.adoc +++ /dev/null @@ -1,14 +0,0 @@ -= Managing module defaults in Fedora - -Setting or changing a *default stream* or a *default installation profile* of a module is in most cases similar to changing a major version of a package. Setting or changing the default stream or the default installation profile requires a Fedora Change request, and it is only allowed in between Fedora releases. - -== Setting or changing a default - -Submit an issue to Fedora Releng in https://pagure.io/releng/issues[pagure.io/releng]. You also need to https://fedoraproject.org/wiki/Changes/Policy#For_developers[submit a Fedora Change]. - -To check the current defaults, have a look at the https://pagure.io/releng/fedora-module-defaults[fedora module defaults repository]. - -Setting or changing default stream of a module will be considered based on the following rules: - -* If the module stream does not mask any part of the Traditional RPM repos, it may be set as a default stream. For example, any module that is entirely a leaf or one that fulfills the function of a package moved from the traditional repos into the modular repos (e.g. `nodejs:8` might replace the `nodejs` traditional package) -* If the module stream masks part of the Traditional RPM repos (e.g it replaces an existing RPM or it introduces a non-trivial set of conflicts) it may not be made a default stream without the express permission of FESCo. Release engineering will be responsible for escalating any PR that is questionable on this point to FESCo for a final decision. \ No newline at end of file diff --git a/en-US/making-modules/updating-modules.adoc b/en-US/making-modules/updating-modules.adoc deleted file mode 100644 index fb9a76a..0000000 --- a/en-US/making-modules/updating-modules.adoc +++ /dev/null @@ -1,103 +0,0 @@ -= Updating modules in Fedora - -This page will guide you through the process of updating an existing module. - -== Step 1: Update your RPM packages - -**Goal**: Get updates for your PRM packages pushed into the Fedora Distribution Git (dist-git). - -=== Workflow Summary: - -1. Make changes to your RPM package sources. -2. Push your RPM package sources to dist-git. - -=== Details: - -Useful resources: - -* https://fedoraproject.org/wiki/Packaging:Guidelines[Fedora Packaging Guidelines] -* https://fedoraproject.org/wiki/Package_maintenance_guide[Fedora Package Maintenance Guide] - -== Step 2: Bump the module version - -**Goal**: Get your module definition describing the new version pushed into the Fedora Distribution Git (dist-git). This needs to be done even when the modulemd doesn't change. - -=== Workflow Summary: - -1. Push an empty commit to your module dist-git repository. - -=== Details: - -The version of your module is taken from the last commit timestamp. Therefore, in order to submit a new module build, you need to make a new commit. To push an empty commit to your modulemd, run: - ----- -$ fedpkg clone modules/nodejs -$ cd nodejs -$ git commit --allow-empty -m "update" -$ git push ----- - -== Step 3: Build your module - -**Goal**: Get your packages built as a module. - -=== Steps: - -1. Submit a module build using fedpkg. -2. Make sure your build succeeded. - -=== Details: - -Module builds are triggered using `fedpkg` from whithin your dist-git repository. - -For example, to submit a build of the `nodejs:10` module, run: - ----- -$ fedpkg clone modules/nodejs -$ cd nodejs -$ git checkout 10 -$ fedpkg module-build ----- - -NOTE: Please note the module build ID. You will need it to verify the build state. It also helps you in the next step. - -To watch the satate of your module build, run: - ----- -$ fedpkg module-build-watch BUILD_ID ----- - -When the module is in a "ready" state, you can continue to the next step. - - -== Step 4: Make your module available to users - -**Goal**: Make your module go through Bodhi — the Fedora updates system. - -=== Steps: - -1. Submit your module as an update in Bodhi. -2. Make sure your update has passed potential user testing. - -=== Details: - -To submit your module as an update, go to https://bodhi.fedoraproject.org/[Fedora Bodhi]. Make sure you are logged in, and then click on Create / New Update at the top-right corner. Fill out the following fields: - -* Candidate Builds: MODULE_BUILD_ID -* Update notes: notes for the users -* Final details: check what applies - -One way of geting the MODULE_BUILD_ID is running the same command as in the previous step: - ----- -$ fedpkg module-build-watch BUILD_ID ----- - -and changing the "koji tag" value in the following way: - ----- -module-nodejs-10-20180607142235-6c81f848 <- koji tag - nodejs-10-20180607142235.6c81f848 <- MODULE_BUILD_ID ----- - -that is removing the "module-" part at the beginning, and replacing the last "-" with a ".". \ No newline at end of file diff --git a/index-main.html b/index-main.html deleted file mode 100644 index ba5381a..0000000 --- a/index-main.html +++ /dev/null @@ -1,141 +0,0 @@ - - - - - - - - - Fedora Modularity Docs Website - - - - - - - - - - - - - - -
    -
    -
    - -
    -
    -
    -
    -

    Fedora Modularity Docs Site

    -

    Test Build.

    -
    -
    -
    Fedora Modularity Docs
    -
    - -  Documentation - -
    -
    -
    -
    -
    -
    -
    -
    -
    -

    About

    -
    -
    -
    About Fedora
    -
    Sponsors
    -
    Fedora Magazine
    -
    Legal
    -
    -
      -
    • - -
      • -
    • - -
      • -
    • - -
      • -
    -
    -
    - -
    -

    Download

    -
    -
    -
    Get Fedora Workstation
    -
    Get Fedora Server
    -
    Get Fedora Atomic
    -
    Fedora Spins
    -
    Fedora Labs
    -
    Fedora ARM®
    -
    Alternative Downloads
    - -
    -
    -
    - -
    -

    Support

    -
    -
    -
    Get Help
    -
    Ask Fedora
    -
    Common Bugs
    -
    Fedora Developer Portal
    -
    Installation Guide
    -
    -
    -
    - -
    -

    Join

    -
    -
    -
    Join Fedora
    -
    Planet Fedora
    -
    Fedora SIGs
    -
    Fedora Account System
    -
    Fedora Community
    -
    -
    -
    -
    - -
    -
    -
    - -
    -
    -
    -
    - - -

    © 2017 Red Hat, Inc. and others. Please send any comments or corrections to the websites team

    -
    -
    -
    - -
    -
    -
    - - - - - - diff --git a/modules/ROOT/assets/images/mod-doc-build-matrix.png b/modules/ROOT/assets/images/mod-doc-build-matrix.png new file mode 100644 index 0000000..8f58a39 Binary files /dev/null and b/modules/ROOT/assets/images/mod-doc-build-matrix.png differ diff --git a/modules/ROOT/assets/images/mod-doc-build-more-releases.png b/modules/ROOT/assets/images/mod-doc-build-more-releases.png new file mode 100644 index 0000000..63f7e92 Binary files /dev/null and b/modules/ROOT/assets/images/mod-doc-build-more-releases.png differ diff --git a/modules/ROOT/assets/images/mod-doc-build-more-versions.png b/modules/ROOT/assets/images/mod-doc-build-more-versions.png new file mode 100644 index 0000000..0869c97 Binary files /dev/null and b/modules/ROOT/assets/images/mod-doc-build-more-versions.png differ diff --git a/modules/ROOT/assets/images/mod-doc-module.png b/modules/ROOT/assets/images/mod-doc-module.png new file mode 100644 index 0000000..a5a153c Binary files /dev/null and b/modules/ROOT/assets/images/mod-doc-module.png differ diff --git a/modules/ROOT/assets/images/mod-doc-package.png b/modules/ROOT/assets/images/mod-doc-package.png new file mode 100644 index 0000000..05e4223 Binary files /dev/null and b/modules/ROOT/assets/images/mod-doc-package.png differ diff --git a/modules/ROOT/assets/images/mod-doc-release.png b/modules/ROOT/assets/images/mod-doc-release.png new file mode 100644 index 0000000..79f9d0d Binary files /dev/null and b/modules/ROOT/assets/images/mod-doc-release.png differ diff --git a/modules/ROOT/assets/images/mod-doc-repositories.png b/modules/ROOT/assets/images/mod-doc-repositories.png new file mode 100644 index 0000000..734cbe8 Binary files /dev/null and b/modules/ROOT/assets/images/mod-doc-repositories.png differ diff --git a/modules/ROOT/assets/images/mod-doc-stream-builds.png b/modules/ROOT/assets/images/mod-doc-stream-builds.png new file mode 100644 index 0000000..6896f32 Binary files /dev/null and b/modules/ROOT/assets/images/mod-doc-stream-builds.png differ diff --git a/modules/ROOT/assets/images/mod-doc-stream.png b/modules/ROOT/assets/images/mod-doc-stream.png new file mode 100644 index 0000000..029d74d Binary files /dev/null and b/modules/ROOT/assets/images/mod-doc-stream.png differ diff --git a/modules/ROOT/assets/images/mod-doc-trad-builds.png b/modules/ROOT/assets/images/mod-doc-trad-builds.png new file mode 100644 index 0000000..d525e25 Binary files /dev/null and b/modules/ROOT/assets/images/mod-doc-trad-builds.png differ diff --git a/modules/ROOT/assets/images/modularity-appstream-overview.png b/modules/ROOT/assets/images/modularity-appstream-overview.png new file mode 100644 index 0000000..c288149 Binary files /dev/null and b/modules/ROOT/assets/images/modularity-appstream-overview.png differ diff --git a/modules/ROOT/assets/images/modularity-building-modules.png b/modules/ROOT/assets/images/modularity-building-modules.png new file mode 100644 index 0000000..ae6dbcd Binary files /dev/null and b/modules/ROOT/assets/images/modularity-building-modules.png differ diff --git a/modules/ROOT/assets/images/modularity-building-trad.png b/modules/ROOT/assets/images/modularity-building-trad.png new file mode 100644 index 0000000..5e5e89f Binary files /dev/null and b/modules/ROOT/assets/images/modularity-building-trad.png differ diff --git a/modules/ROOT/nav.adoc b/modules/ROOT/nav.adoc new file mode 100644 index 0000000..f2ebc75 --- /dev/null +++ b/modules/ROOT/nav.adoc @@ -0,0 +1,17 @@ +* xref:architecture.adoc[How does it work] +** xref:architecture/building.adoc[Building Software] +*** xref:architecture/building/name-and-id.adoc[Module name and ID] +** xref:architecture/consuming.adoc[Consuming Software] +*** xref:architecture/consuming/dnf-behavior.adoc[DNF Behavior] +* xref:making-modules.adoc[Making Modules] +** xref:making-modules/adding-new-modules.adoc[Adding New Modules] +** xref:making-modules/updating-modules.adoc[Updating Modules] +** xref:making-modules/inspecting-build-failures.adoc[Inspecting Build Failures] +** xref:making-modules/building-modules-locally.adoc[Building Modules Locally] +** xref:making-modules/defining-modules.adoc[Defining Modules in modulemd] +** xref:making-modules/managing-defaults.adoc[Managing Defaults] +* xref:using-modules.adoc[Using Modules] +* xref:community.adoc[Community] +** xref:community/teams.adoc[Teams and Working Groups] +* xref:faq.adoc[FAQ] +* xref:references.adoc[References] \ No newline at end of file diff --git a/modules/ROOT/pages/_partials/submit-module-build.adoc b/modules/ROOT/pages/_partials/submit-module-build.adoc new file mode 100644 index 0000000..4ca1c26 --- /dev/null +++ b/modules/ROOT/pages/_partials/submit-module-build.adoc @@ -0,0 +1,29 @@ +**Goal**: Get your packages built as a module. + +=== Steps: + +1. Submit a module build using fedpkg. +2. Make sure your build succeeded. + +=== Details: + +Module builds are triggered using `fedpkg` from whithin your dist-git repository. + +For example, to submit a build of the `nodejs:10` module, run: + +---- +$ fedpkg clone modules/nodejs +$ cd nodejs +$ git checkout 10 +$ fedpkg module-build +---- + +NOTE: Please note the module build ID. You will need it to verify the build state. It also helps you in the next step. + +To watch the satate of your module build, run: + +---- +$ fedpkg module-build-watch BUILD_ID +---- + +When the module is in a "ready" state, you can continue to the next step. \ No newline at end of file diff --git a/modules/ROOT/pages/_partials/submit-module-update.adoc b/modules/ROOT/pages/_partials/submit-module-update.adoc new file mode 100644 index 0000000..e0f04bd --- /dev/null +++ b/modules/ROOT/pages/_partials/submit-module-update.adoc @@ -0,0 +1,29 @@ +**Goal**: Make your module go through Bodhi — the Fedora updates system. + +=== Steps: + +1. Submit your module as an update in Bodhi. +2. Make sure your update has passed potential user testing. + +=== Details: + +To submit your module as an update, go to https://bodhi.fedoraproject.org/[Fedora Bodhi]. Make sure you are logged in, and then click on Create / New Update at the top-right corner. Fill out the following fields: + +* Candidate Builds: MODULE_BUILD_ID +* Update notes: notes for the users +* Final details: check what applies + +One way of geting the MODULE_BUILD_ID is running the same command as in the previous step: + +---- +$ fedpkg module-build-watch BUILD_ID +---- + +and changing the "koji tag" value in the following way: + +---- +module-nodejs-10-20180607142235-6c81f848 <- koji tag + nodejs-10-20180607142235.6c81f848 <- MODULE_BUILD_ID +---- + +that is removing the "module-" part at the beginning, and replacing the last "-" with a ".". \ No newline at end of file diff --git a/modules/ROOT/pages/architecture.adoc b/modules/ROOT/pages/architecture.adoc new file mode 100644 index 0000000..d861905 --- /dev/null +++ b/modules/ROOT/pages/architecture.adoc @@ -0,0 +1,71 @@ += Main Concepts of Modularity + +Modularity reuses some existing and creates some new concepts in the build and release process in Fedora. + +== Packages + +image::mod-doc-package.png[,80%,] + +We are reusing packages as they are. + +Packages are the smallest unit of software delivery. +Right now, Fedora uses RPM packages to build and ship all of its software. +There is a distinction between source RPM (SRPM) packages and binary RPM packages. + +As the name suggests, *source packages* contain the source code, but also the build process definition including a list of build dependencies. +Building a source package results in one or multiple binary packages. + +*Binary packages* are produced by building source packages in a build environment called a buildroot. +Different buildroots produce different binary packages. +This means that a source package without a context is not a complete definition of a resulting binary package. + +Every Fedora release has its own buildroot. +Even when multiple releases contain the same package using the same source, they are built multiple times, once in each buildroot, producing different (and often incompatible) binary packages. +Also, over time, as the distribution gets updated, so does its buildroot. +As a result, a package built today may not result in the same binary as a package built tomorrow. + +*Packages are either a part of a release, or a part a module.* + +== Releases + +image::mod-doc-release.png[,80%,] + +Releases are the generations of Fedora e.g. “Fedora 28”, “Fedora 29”, or “epel 7”. + +Each release can only contain one major version of every package (by policy). +In general, Fedora tends to ship the latest stable versions of software available. +At the same time, packages need to maintain a certain API/ABI stability throughout the lifecycle of the release they are part of. + +The problem with this approach is finding the right balance of being too fast vs. too slow. +For example, developers in general tend to prefer the newest versions of software, while server administrators want API/ABI stability for a longer period of time. +This problem is solved by Modules. + +== Modules and Streams + +image:mod-doc-module.png[,80%,] + +*Modules* are collections of packages representing a logical unit e.g. an application, a language stack, a set of tools. +These packages are built, tested, and released together. + +Each module defines its own lifecycle which is closer to the upstream rather than the Fedora release. + +Modules are the mechanism of delivering multiple streams (versions) of software for the same release. +This also works the other way round, the same stream for multiple releases. + +image::mod-doc-stream.png[,80%,] + +A *stream* is a series of versions having a goal such as backwards API/ABI compatibility or delivering the latest stable version. +A “nodejs” interpreter can have streams such as https://src.fedoraproject.org/modules/nodejs/branch/6[6] or https://src.fedoraproject.org/modules/nodejs/branch/8[8] (two current versions of nodejs), but also “devel” or “latest”. +Some packages don’t have a major version. +An example could be the “calc” package that is being developed in two branches “stable” and “unstable”. + +Simply put, streams are the mechanism of delivering and updating software at different speeds, allowing developers to have bleeding-edge software, and server admins longer stability. + +== Artifacts + +image::mod-doc-repositories.png[,80%,] + +Artifacts are consumable outputs of the build and release processes e.g. an iso image, an RPM repository, a container base image, or an ostree tree. + +Modules will be delivered as an RPM repository that will work on top of existing releases. +This repository will also be available in the Fedora container base image, enabling users to build containers with multiple versions of software. diff --git a/modules/ROOT/pages/architecture/building.adoc b/modules/ROOT/pages/architecture/building.adoc new file mode 100644 index 0000000..bd6fc61 --- /dev/null +++ b/modules/ROOT/pages/architecture/building.adoc @@ -0,0 +1,55 @@ += Building Software with Modularity + +This is a high-level overview of how builds work with Fedora Modularity and how it compares with traditional builds. + +== Traditional package builds + +image::mod-doc-trad-builds.png[,80%,] + +In the existing Fedora world, packages are maintained in branches that map to specific Fedora releases. +Package repositories have branches e.g. “f27” for Fedora 27, “f28” for Fedora 28, etc. + +There are no changes to the existing packager workflow. +Maintaining release-specific branches and using the existing commands to build them keep working. + +== Modular package builds + +image::mod-doc-stream-builds.png[,80%,] + +Modularity changes package branching to be version-focused. + +Branching packages according to their major version as opposed to the distribution release brings more clarity — because we can see what lives in a branch, and removes source duplication — because there is one branch per version. + +While this approach makes more sense from the software perspective, there is no longer a clear mapping of a package branch to a particular release. +Modules are a way of defining this. + +== Building one source for multiple releases + +image::mod-doc-build-more-releases.png[,40%,] + +Modules define what package branches are built for which Fedora releases. +One module can be built for multiple releases. + +The above example produces three different binaries, one for each release. In case there are multiple architectures, three binaries will be produced (one each). + +== Building multiple versions + +image::mod-doc-build-more-versions.png[,40%,] + +Multiple versions of packages can be built for one release by defining multiple modules. +Users are able to choose which version they want to use on their system. + +The above example produces two different binaries, each with a different Python version. +Again, in case there are multiple architectures, two binaries will be produced for each one. + +Modularity also leverages existing technologies such as containers to enable users to run multiple versions at the same time on one "machine." + +== Building against multiple versions + +image::mod-doc-build-matrix.png[,60%,] + +Modules can be also be built against other modules to achieve more complex results. +Client tooling always makes sure the right version is installed for a given context. + +The above example produces two different binaries, each bound to a different Python version. +Again, in case there are multiple architectures, two binaries will be produced for each one. diff --git a/modules/ROOT/pages/architecture/building/name-and-id.adoc b/modules/ROOT/pages/architecture/building/name-and-id.adoc new file mode 100644 index 0000000..115a51d --- /dev/null +++ b/modules/ROOT/pages/architecture/building/name-and-id.adoc @@ -0,0 +1,52 @@ += Naming and identifying modules in Fedora + +Modules are uniquely identified by NSVCA which stands for _name_, _stream_, _version_, _context_, and _architecture_. This page describes both the source-level ID (NSV) and the binary-level ID (NSVCA). + +== Source-level ID (NSV) + +At the source level, modules are only identified by the first three: _name_, _stream_, and _version_. Name is defined as a name of the module's repository in DistGit, stream is a name of the branch in DistGit, and version is the timestamp of a commit. + +=== 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 (NSVCA) + +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.). + +Module binaries use the full NSVCA — so in addition to the _name_, _stream_, and _version_ fields described above, there are two more for binaries: _architecture_ and _context_. + +=== 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/modules/ROOT/pages/architecture/consuming.adoc b/modules/ROOT/pages/architecture/consuming.adoc new file mode 100644 index 0000000..b027715 --- /dev/null +++ b/modules/ROOT/pages/architecture/consuming.adoc @@ -0,0 +1,61 @@ += Consuming Software with Modularity + +This is a high-level overview of how users can install software with Fedora Modularity and how is it different from the traditional workflow(s). + +== Understanding the Delivery Channels + +Modular Fedora will ship with two sets of repositories: + +. The *traditional base repository* representing the distribution as we know it today — there are no user-visible changes in this part. + +. A new *modular repository* (often referred to as the "Application Stream" or AppStream for short) including all the additional versions delivered as modules. + +The Modules repository will be optional for users. + +image::mod-doc-repositories.png[,80%,] + +== Consuming the traditional packages + +There are no changes to the traditional user experience. +Packages from the traditional repository will be installed and updated using the same methods as before. +Everything keeps working as it used to. + +== Consuming the modular packages + +If a user desires to use the optioanl Modular repositories in order to consume non-default versions of software, there will be some new concepts introduced in the client tooling to manage them. +We outline these below. + +=== Enabling a module + +Enabling a module makes its packages available on the system. +Packages delivered as part of a module always have a priority over the ones from the traditional base, regardless of their actual version. +Packages in modules are often replacements of the ones in the traditional base. + +Modularity brings parallel availability, not parallel installability. +Only one stream of a given module can be enabled on a system — so it is always clear which version gets installed. +Installing and running multiple versions of software can be achieved by using existing technologies, such as containers. + +=== Installing a module + +To make installation easy, some modules can be also installed as a unit, without the need of enabling them first and then installing individual packages. +Installing a module doesn’t necessarily mean installing all of its packages. +Modules can define something called an "installation profile" to help users with the installation. + +==== Installation profile + +Installation profiles are essentially lists of packages that help users with the module installation. To give a specific example, a database module could have two profiles: server and client. This helps the user to install what they need without the need of thinking about the package names. However, installation profiles are just an optional feature and users can still install packages directly. + +==== Updating the system + +Updating the system always respects user’s module choices (or lack of module) even when there are multiple (and possibly higher) versions available. + +If the user doesn’t enable any modules, all packages on their system get updated to the latest versions provided by the traditional base repository. +However, if the user enables a module stream, packages get updated to the newest version provided by the module. + +Thanks to this mechanism, the user has better control over the versions of packages on their system while receiving updates (such as security patches) for the whole system. + +==== Running multiple versions using containers + +Modularity brings parallel availability, not parallel installability. There are other technologies i.e. linux containers or software collections that deal with this. + +All the steps described above can be used in a container the same way as on a traditional system. Producing up-to-date containers with multiple versions of software in an automated way is also one of the goals. diff --git a/modules/ROOT/pages/architecture/consuming/dnf-behavior.adoc b/modules/ROOT/pages/architecture/consuming/dnf-behavior.adoc new file mode 100644 index 0000000..c002d4e --- /dev/null +++ b/modules/ROOT/pages/architecture/consuming/dnf-behavior.adoc @@ -0,0 +1,142 @@ += Modular DNF Behavior + +This page captures the key behaviors of modular DNF. + +== Definitions + +* Ursine ("bare") packages are those that are not part of any module. +* A module's "context" is a unique hash value generated by the build + system to distinguish binaries built for different Fedora releases as + a result of stream expansion. + See <>. + +== General + +* Existing use of RPM-based operations must not change and must + continue to work just as they always have. +* DNF install/update commands can be invoked by using syntax of either + `dnf module $modspec ...` or `dnf @$modspec ...`. +* The "platform" pseudo-module cannot be explicitly enabled, installed, + deleted, or have its stream changed. +* A module is specified by its name, stream, version, context, and + architecture (eg., "module:stream:version:context:arch"). +** If a module has a default stream defined on a system, "stream" may be + omitted. Otherwise, "stream" must be explicitly provided. +** For a given "module:stream", "version" can always be omitted. If + "version" is not explicitly provided, the latest "version" for the + given "module:stream" will be chosen. +** If the module "context" is not specified, DNF will use heuristics to + determine the appropriate "context". + See <>. +** If the module "arch" is not specified, the system's base architecture + will be used. +** Specifying a non-existent "module" name should fail. +** Specifying a non-existent "stream" (for a valid "module") should fail. +** Specifying specifying a non-existent "version" + (for a valid "module:stream") should fail. +** Specifying specifying a non-existent "context" + (for a valid "module:stream:version") should fail. +** Specifying a non-existent "arch" + (for a valid "module:stream:version:context") should fail. + +== System modular defaults + +* DNF must look for modular default stream and installation profile + data in the repodata of the package installation repos--which is + sourced from <> during the Fedora build + and release process. +* DNF must look for _override_ data for modular default stream and + installation profile on the local system in + `/etc/dnf/modules.defaults.d/`. + +== Module listing + +* DNF must be able to list all modular content (modules, streams, + enabled streams, default streams, profiles, module packages, + profile packages). + +== Module enablement + +* Enabling a module stream makes all of its packages available on the + system, but does not install them. +* At most one stream of a module may be enabled at a time on a system. +* Enabling a different stream of a module must be confirmed by the user + (or "--assumeyes"). +* Enabling a different stream of a module will automatically disable + the old stream. + +== Module Auto-enablement + +* If an uninstalled/unenabled module has a valid default stream + configured, DNF will consider the default stream of the module and + all of its packages available for resolving dependencies--and will + automatically enable the default stream of that module if any packages + from it are installed directly or indirectly (to resolve dependencies). +* If an uninstalled/unenabled module:stream is listed as a runtime + dependency of another module being installed or enabled, DNF will + automatically enable that dependency. +* Once a particular stream of a module has been enabled, DNF may not + automatically enable a different stream. + +== Module/package installation + +* Installing a module enables the specified stream (or default stream, + if not specified) and installs all of the packages associated with the + specified profile (or "default" profile, if not specified). +* If a module does not explicitly have a "default" profile specified it + its modulemd, DNF must pretend that it exists and is empty. + See <>. +* Each profile of a module stream must be able to be installed. + However, a module's profiles may conflict amongst themselves such + that they cannot all be installed at the same time. + (A hypothetical example would be a module that provides something + analogous to the coreutils and coreutils-single packages in different + profiles. The coreutils packages provide the same functionality, but + conflict.) + +== Module update + +* Updating a module will update all installed packages that belong to + the enabled module stream--regardless if the packages were installed + by an install profile or ad-hoc. + +== Module disablement + +* Disabling a module does not remove any packages that belong to the + module. +* Disabling a module disables modules that depend on it--unless they + still have packages installed. + +== Module removal + +* Uninstalling a module removes all the packages that belong to the + module and disables it. +* Ad-hoc removal of all packages from an installed module does not + disable the module. + +== Module locking + +* A locked module cannot have a different stream enabled or be + disabled--without first unlocking it. + +== Stream expansion and contexts + +* Packages from module contexts that do not match the current + transaction are disregarded. + See <>. + +== Other + +* Any package in an enabled module takes priority over any ursine RPM + with the same package name, regardless of which repositories those + modules and packages may be in. +* If there's an ursine or modular RPM with a higher NVR than the hotfix + one, the ursine or modular one wins. This is to ensure new proper + updates override the temporary hotfix RPMs. + +[bibliography] +== References + +* [[[mmd-spec-v2]]] https://github.com/fedora-modularity/libmodulemd/blob/master/spec.v2.yaml +* [[[fedora-module-defaults-repo]]] https://pagure.io/releng/fedora-module-defaults +* [[[module-stream-expansion]]] https://fedoraproject.org/wiki/Infrastructure/Factory2/Focus/StreamExpansion diff --git a/modules/ROOT/pages/community.adoc b/modules/ROOT/pages/community.adoc new file mode 100644 index 0000000..7d475db --- /dev/null +++ b/modules/ROOT/pages/community.adoc @@ -0,0 +1,31 @@ += Communication + +This page lists the communication channels and meetings of members of the Modularity Working Group (Modularity WG). + + +== Channels + +There are two main communication channels the Modularity WG uses: + +:hash: # + +https://webchat.freenode.net/?channels=fedora-modularity[{hash}fedora-modularity] on freenode:: +Most of the discussions happen on this IRC channel. + +https://lists.fedoraproject.org/archives/list/devel@lists.fedoraproject.org/[devel@lists.fedoraproject.org]:: +The Modularity WG doesn't have a dedicated mailng list. +Instead, the Fedora Devel mailing list is used time to time for more complex decisions or announcements. + +https://lists.fedoraproject.org/archives/list/server@lists.fedoraproject.org/[server@lists.fedoraproject.org]:: +The https://fedoraproject.org/wiki/Server[Server SIG] also discusses Modularity at times as the Server Edition is a primary stakeholder in the goals of the https://fedoraproject.org/wiki/Objectives#Current[Modularity Objective]. + +== Meetings + +Meetings are listed on the https://apps.fedoraproject.org/calendar/modularity/[Modularity calendar]. +Currently, there are two alternating meetings on Tuesday: + +Modularity WG:: +A formal meeting of the Modularity WG to discuss, post updates, and make dedisions. + +Office Hours:: +No formal agenda, members of the Modularity WG promise to be present at this time for questions or discussion. diff --git a/modules/ROOT/pages/community/teams.adoc b/modules/ROOT/pages/community/teams.adoc new file mode 100644 index 0000000..d3f6a1e --- /dev/null +++ b/modules/ROOT/pages/community/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/modules/ROOT/pages/faq.adoc b/modules/ROOT/pages/faq.adoc new file mode 100644 index 0000000..2af6988 --- /dev/null +++ b/modules/ROOT/pages/faq.adoc @@ -0,0 +1,36 @@ += Frequently Asked Questions (FAQ) + +[qanda] +Exactly what problem are you trying to solve?:: + The “too fast vs. too slow” problem, outdated containers, and complex packaging workflow. + See The Problem to be Solved page for more detailed information. +How is this different from containers?:: + This is a build step that happens before containers. + Modularity provides parallel availability of multiple versions that can be consumed by containers to enable parallel installation. +How does this differ from Software Collections (SCLs)?:: + Modularity is about building multiple versions of packages, and making them all available to users. + SCLs are about installing software in parallel using RPM. + These two don’t overlap, they complement each other. You can build a Modular SCL. +Couldn’t we solve this with having compat- packages, or putting versions into package names for different version streams?:: + That works technically, but the packaging workload doesn’t scale, and dependency interactions become complex. This will let packagers make more content available to users without an explosion of effort. + Modules also help to solve the discoverability problem. + For example, is httpd v2.4 in a package called httpd-2-4 or http-2? +Can I install more versions at once?:: + Modularity does not invent a new technology for parallel installation. + Existing solution such as containers or Software Collections can be used to achieve this. +How is this different from RPM? Why not just different repos?:: + Technical: DNF performance with many repositories. We envision having tens or even hundreds of modules available to a single system. + + User experience: A repository is a source of software provided by a vendor, not necessarily representing a single application, language stack, or any other logical unit of software. + A repository typically contains multiple applications, stacks, etc. + We do not want to change this concept. +Are you going to produce all versions? What lifecycles and versions are envisioned?:: + We are developing the technology such as the build pipeline and client tooling to enable contributors to build multiple versions. + We envision longer lifecycles of stacks mainly for server, and devel/rolling releases of some stacks for developers. + However, contributors to the Fedora project will be the deciders and maintainers of any versions that are available. +I can just ‘dnf downgrade’ to get an older version.. Why do we need modularity?:: + Using an older version that is no longer maintained can be dangerous, mostly because of the lack of security updates. + Modules, on the other hand, represent a major version that is still being actively maintained by the upstream and therefore should receive updates. +Is this different from single app VMs with custom versions?:: + This helps with a single app VM with custom versions. + Same as with containers, it helps users to get the right version for their system. + diff --git a/modules/ROOT/pages/index.adoc b/modules/ROOT/pages/index.adoc new file mode 100644 index 0000000..4277104 --- /dev/null +++ b/modules/ROOT/pages/index.adoc @@ -0,0 +1,53 @@ += What is Modularity + +Modularity introduces a new optional repository to Fedora called Modular (often referred to as the "Application Stream" or AppStream for short) that ships additional versions of software on independent lifecycles. +This way users can keep their operating system up-to-date while having the right version of an application for their use case, even when the default version in the distribution changes. + +image::modularity-appstream-overview.png[,100%,] + + +== What Problems does Modularity Solve? + +=== Too fast vs. too slow + +Different users have different needs. +Developers want the latest versions possible, system administrators want stability for longer period of time. +There are many Linux distributions out there, each targetting a different audience, for example Fedora vs CentOS. + +Fedora generally ships the latest stable versions of its component packages when it is released twice per year. +That is convenient for desktop users and developers. +Even though many people use Fedora on a server, it is sometimes necessary to have a stable version of certain packages for a longer time, mostly because of third-party applications. + +At the same time, some people consider Fedora to be moving too slowly for them and want even newer runtimes on their system. +Some upstreams release their software faster than twice a year. + +On the other hand, CentOS targets long-term stability and releases a new version once every few years. +This is convenient for server admins as there are fewer changes over longer periods of time. +But some of the software gets old for modern applications and newer versions of runtimes might be needed. + +In other words, it would be convenient to be able to choose some parts of the system to be moving slowly, and other parts to be moving faster. +Can we do that? + +https://example.com[YES!] + +=== Outdated containers + +There are many containers out there. +The majority of them are built manually, not actively maintained, not patched with security fixes, and still used by many people. +This is especially true for the ones using software of a different version than the distribution their are based on provides. + +If Fedora had multiple versions of software that is actively maintained and built, could we use it to produce containers? +Could these containers get automatically rebuilt every time the packages get updated? + +https://example.com[YES!] + +=== Complex packager workflows + +Fedora contributors maintain their packages in multiple branches — one for each release. +Even when the packages are the same. +Leading to a series of manual steps associated with the build process. + +Could we enable packagers to maintain packages in branches that would follow the package version instead of an arbitrary distribution release version? +Having a single branch that builds across multiple releases would save some work for packagers. + +https://example.com[YES!] diff --git a/modules/ROOT/pages/making-modules.adoc b/modules/ROOT/pages/making-modules.adoc new file mode 100644 index 0000000..e467a44 --- /dev/null +++ b/modules/ROOT/pages/making-modules.adoc @@ -0,0 +1,5 @@ += Making Modules for Fedora + +If you wish to maintain an additional version of an application, language stack, or any other piece of software, modules might be the way to go for you. + +The xref:making-modules/adding-new-modules.adoc[Adding New Modules] covers the whole process of adding a new module to Fedora. \ No newline at end of file diff --git a/modules/ROOT/pages/making-modules/adding-new-modules.adoc b/modules/ROOT/pages/making-modules/adding-new-modules.adoc new file mode 100644 index 0000000..67c40e7 --- /dev/null +++ b/modules/ROOT/pages/making-modules/adding-new-modules.adoc @@ -0,0 +1,76 @@ += Adding new modules to Fedora + +This page will guide you through the whole process of adding a new module to Fedora. There is also an official https://fedoraproject.org/wiki/Modularity/Adding_New_Modules_and_Managing_Defaults[process for adding new modules] which will give you a summary of the major steps you need to undergo, and is the authoritative point of truth. + +== Step 1: Get your RPM packages in place + +**Goal**: Get your RPM package(s) pushed into the Fedora Distribution Git (dist-git). + +=== Workflow Summary: + +1. Create your new RPM package. +2. Submit your package for Fedora Review. (only for new packages) +3. Request a new repository and/or a branch in dist-git. +4. Push your package sources into dist-git. + +=== Details: + +When creating your new http://rpm.org/[RPM package], please make sure it complies with the https://fedoraproject.org/wiki/Packaging:Guidelines[Fedora Packaging Guidelines]. + +NOTE: If you adding a new branch to an existing package, you can skip the review part and proceed to requesting a new branch. + +To learn about the Fedora review, requesting repositories and branches, and pushing sources to dist-git, please see the https://fedoraproject.org/wiki/Package_Review_Process#Contributor[Fedora Package Review Process] + +== Step 2: Get your module definition in place + +**Goal**: Get your module definition pushed into the Fedora Distribution Git (dist-git). + +=== Steps: + +1. Write a modulemd. +2. Request a new repository and/or a branch in dist-git. +3. Push your modulemd into dist-git. + +=== Details: + +Writing a modulemd is covered in detail in the xref:making-modules/defining-modules.adoc[Defining Modules in modulemd] section. + +NOTE: Running the following `fedpkg` commands requires a ticket to be created at https://pagure.io/settings/token/new and saved in `\~/.config/rpkg/fedpkg.conf` + +WARNING: Please remember that the name of your module will be the name of your repository. The same way, the stream name of your module will be the name of the branch. Both of these will be visible to users. + +To request a new repository in dist-git, for example for a `nodejs` module, run: + +---- +$ fedpkg --module-name modules/nodejs request-repo --exception +---- + +And to request a new branch, for example for a `nodejs:10` module, run: + +---- +$ fedpkg --module-name modules/nodejs request-branch 10 +---- + +To push your modulemd into dist-git, clone the dist-git repository, change to the correct branch, add your modulemd, and push it as you would in git. + +NOTE: Please make sure that the name of your modulemd file matches the name of the dist-git repository. + +For example, to push the `nodejs:10` module definition, run: + +---- +$ fedpkg clone modules/nodejs +$ cd nodejs +$ git checkout 10 +$ vim nodejs.yaml +$ git add nodejs.yaml +$ git commit -m "add the initial modulemd" +$ git push +---- + +== Step 3: Build your module + +include::{partialsdir}/submit-module-build.adoc[] + +== Step 4: Make your module available to users + +include::{partialsdir}/submit-module-update.adoc[] \ No newline at end of file diff --git a/modules/ROOT/pages/making-modules/building-modules-locally.adoc b/modules/ROOT/pages/making-modules/building-modules-locally.adoc new file mode 100644 index 0000000..163ce7b --- /dev/null +++ b/modules/ROOT/pages/making-modules/building-modules-locally.adoc @@ -0,0 +1,62 @@ += Building Fedora modules locally + +This page walks you through building modules locally on your machine. + +== Prerequisities + +You need to install the `module-build-service` as well as `fedpkg`: + +---- +$ sudo dnf install module-build-service fedpkg +---- + +and add yourself to the `mock` group: + +---- +$ sudo usermod -a -G mock USERNAME +$ newgrp +---- + +== Step 1: Build your module + +Local builds are started using `fedpkg` from whithin your dist-git repository. + +For example, to submit a build of the `testmodule:master` module, run: + +---- +$ fedpkg clone modules/nodejs +$ cd nodejs +$ git checkout master +$ fedpkg module-build-local +---- + +When the build finishes, you'll be able to find the results in: + +---- +~/modulebuild/builds/MODULE/results/ +---- + +where MODULE is "module-NAME-STREAM-VERSION", so for example "module-testmodule-master-20180612122805". + +== Step 2: Test your module + +WARNING: This requires Fedora 28 or higher. + +To test your module, add the repository to your system by creating an entry similar to this in `/etc/yum.repos.d/test.repo`: + +---- +[local] +name=My Local Repository +baseurl=file:///home/adam/modulebuild/builds/module-testmodule-master-20180612122805/results/ +gpgcheck=0 +enabled=1 +---- + +Please replace "adam" with your user name, and "module-testmodule-master-20180612122805" with the actual value for your module. + +Now, when you list the available modules on your system, you should be able to see it and install it: + +---- +$ dnf module list +$ dnf module install testmodule:master +---- \ No newline at end of file diff --git a/modules/ROOT/pages/making-modules/defining-modules.adoc b/modules/ROOT/pages/making-modules/defining-modules.adoc new file mode 100644 index 0000000..aa3c946 --- /dev/null +++ b/modules/ROOT/pages/making-modules/defining-modules.adoc @@ -0,0 +1,369 @@ += Defining modules in modulemd + +Modules are defined using a https://pagure.io/modulemd[modulemd file]. The definition includes the summary and description, list of source RPM packages, build information i.e. buildroot, and usage information i.e. installation profiles or licenses. + +This page will help you with writing a module definition from scratch. Even though this page is meant to be up-to-date, please make sure your module complies with the https://fedoraproject.org/wiki/Module:Guidelines[Fedora Packaging Guidelines for Modules] as it is the authoritative point of truth. + +This page includes the <>, the <>, examples of <>, and a <>. + +== Common definitions + +Every modulemd starts with these three lines: + +[source,yaml] +---- +document: modulemd +version: 2 +data: + ... <1> +---- + +<1> All the following definitions go here, under _data_. + +=== Information about your module + +Tell users what this module represents by writing a summary and a description, and how can they use it by specifying a license. + +[source,yaml] +---- + summary: An example module + description: >- <1> + A module for the demonstration of the metadata format. Also, + the obligatory lorem ipsum dolor sit amet goes right here. + license: + module: + - MIT <2> +---- + +<1> The `>-` means new line in YAML. Useful for longer blocks of text, such as the description! + +<2> A license for this modulemd file. Fedora content, such as SPEC files or patches not included upstream, uses the MIT license by default, unless the component packager declares otherwise. + + +=== List the packages + +To make your module useful, include some RPM packages in it. List all source RPM packages this module should include. + +[source,yaml] +---- + components: + rpms: + first-package: <1> + rationale: Provides the core functionality. <2> + ref: 3.0 <3> + second-package: + rationale: Web UI for the first-package. + ref: stable + ... <4> +---- + +<1> Name of the package — maps to a DistGit repository name. + +<2> The reason why is this package here. Mostly for humans. + +<3> DistGit branch, tag, or a commit — so the right version of the package gets included. + +<4> List as many packages as you need. + +=== For which releases? + +To build your module for all Fedora releases that are actively maintained, use the following definition. For anything more than this, such as building against other modules or requiring other modules during runtime, please see the Advanced section below. + +[source,yaml] +---- + dependencies: + - buildrequires: + platform: [] + requires: + platform: [] +---- + +=== Help users install it (optional, but encouraged) + +To help users install your module, define installation profiles. These profiles represent a specific use case of your module. Most modules have at least a default profile. But you can specify more. For example, a database module can have a server and a client profile. + +[source,yaml] +---- + profiles: + default: <1> + description: A standard installation. <2> + rpms: + - package-one <3> + - package-one-extras <3> + - package-two <3> + cli: + description: A command-line client. + rpms: + - package-one-cli + ... <4> +---- + +<1> Name of the profile. + +<2> A quick summary of the profile. + +<3> Binary packages to be installed with this profile. + +<4> List as many profiles as you need. + +=== Public API (optional, but encouraged) + +List all binary RPM packages in your module that you consider to be the main stable feature of the module. Other (unlisted) packages should be considered unsupported, or an implementation detail. + +[source,yaml] +---- + api: + rpms: + - package-one + - package-one-extras + - package-one-cli + - package-one-devel + - package-two +---- + +== Advanced definitions + +=== References to the upstream (optional) + +You can also provide references to the upstream community, documentation, or to an issue tracker. + +[source,yaml] +---- + references: + community: http://www.example.com/ <1> + documentation: http://www.example.com/ <2> + tracker: http://www.example.com/ <3> +---- + +<1> Upstream community website, if it exists. + +<2> Upstream documentation, if it exists. + +<3> Upstream bug tracker, if it exists. + +=== Building in a specific order (optional) + +Packages are built in batches. By default, all packages are part of a single group, and therefore built concurently. + +To build packages in a specific order, assign them to multiple build groups. Build groups are identified by an integer. Groups with lower number are built first. Negative values are allowed, `0` is the implicit default value. + +In this specific example, `first-package` gets built first, and `second-package` gets built second. + +[source,yaml] +---- + components: + rpms: + first-package: + rationale: Provides the core functionality. + ref: 3.0 + buildorder: 0 <1> + second-package: + rationale: Web UI for the first-package. + ref: stable + buildorder: 10 <1> +---- + +<1> A number of the build group. + +=== Build macros (optional) + +Use this if you need to build your packages with a specific RPM macro. Applies to all packages in the module. + +[source,yaml] +---- + buildopts: + rpms: + macros: | + %demomacro 1 + %demomacro2 %{demomacro}23 +---- + +=== Advanced dependencies (optional) + +modules can be + +* built against other modules +* require other modules during runtime +* built agains one or more streams of the same module +* work with one or more streams of another module + + +==== Building for a specific Fedora release(s) only + +Building **only for Fedora 28**: + +[source,yaml] +---- + dependencies: + - buildrequires: + platform: [f28] + requires: + platform: [f28] +---- + +Building **for everything else than Fedora 28**: + +[source,yaml] +---- + dependencies: + - buildrequires: + platform: [-f28] + requires: + platform: [-f28] +---- + +Building **only for Fedora 28 and Fedora 29**: + +[source,yaml] +---- + dependencies: + - buildrequires: + platform: [f28, f29] + requires: + platform: [f28, f29] +---- + +==== Depending on other modules + +Your module can also depend on another modules. Specific streams can be referenced the same way as above in "Building for a specific Fedora release(s) only". + +[source,yaml] +---- + dependencies: + - buildrequires: + platform: [] + nodejs: [] + requires: + platform: [] + nodejs: [] +---- + +==== Complex dependencies + +Simple things should simple, complex things should be possible. Let's say my module requires `nodejs` during build and run time. It also requires `build-tools` only during build. To make it even more complex, it also requires a specific stream of a `pizza-module` during build and run time, but only on Fedora 27. + +[source,yaml] +---- + dependencies: + - buildrequires: + platform: [-f27] + buildtools: [v1, v2] + nodejs: [] + requires: + platform: [-f27] + nodejs: [] + - buildrequires: + platform: [f27] + buildtools: [v1, v2] + nodejs: [] + pizza-module: [3.6] + requires: + platform: [f27] + nodejs: [] + pizza-module: [3.6] +---- + +For even more complex scenarios, please study the https://github.com/fedora-modularity/libmodulemd/blob/master/spec.v2.yaml[modulemd specification]. + + +=== Binary packages to exclude (optional) + +One source RPM package might produce multiple binary RPM packages. If you don't want to include some binary packages, list them under `filter`. + +[source,yaml] +---- + filter: + rpms: + - first-package-debuginfo + - second-package-nope +---- + +== A minimal modulemd + +=== An absolute minimum + +This module includes two source RPM packages built for all Fedora releases. + +[source,yaml] +---- +document: modulemd +version: 2 +data: + summary: An example module + description: >- + A module for the demonstration of the metadata format. Also, + the obligatory lorem ipsum dolor sit amet goes right here. + license: + module: + - MIT + dependencies: + - buildrequires: + platform: [] + requires: + platform: [] + components: + rpms: + first-package: + rationale: Provides the core functionality. + ref: 3.0 + second-package: + rationale: Web UI for the first-package. + ref: stable +---- + +=== Including profiles and API (recommended) + +This module includes two source RPM packages built for all Fedora releases. It makes clear which packages are considered the API, and helps users with installation thanks to the profiles. + +[source,yaml] +---- +document: modulemd +version: 2 +data: + summary: An example module + description: >- + A module for the demonstration of the metadata format. Also, + the obligatory lorem ipsum dolor sit amet goes right here. + license: + module: + - MIT + dependencies: + - buildrequires: + platform: [] + requires: + platform: [] + api: + rpms: + - package-one + - package-one-extras + - package-one-cli + - package-one-devel + - package-two + profiles: + default: + description: A standard installation. + rpms: + - package-one + - package-one-extras + - package-two + cli: + description: A command-line client. + rpms: + - package-one-cli + components: + rpms: + first-package: + rationale: Provides the core functionality. + ref: 3.0 + second-package: + rationale: Web UI for the first-package. + ref: stable +---- + +=== Bonus: Converting modulemd v1 to v2 + +This video walks through the differences between the legacy modulemd v1 and the current modulemd v2. + +++++ + +++++ \ No newline at end of file diff --git a/modules/ROOT/pages/making-modules/inspecting-build-failures.adoc b/modules/ROOT/pages/making-modules/inspecting-build-failures.adoc new file mode 100644 index 0000000..82463f8 --- /dev/null +++ b/modules/ROOT/pages/making-modules/inspecting-build-failures.adoc @@ -0,0 +1,19 @@ += Inspecting module build failures in Fedora + +Have you submitted a build which failed? This page will point you to the right places to get all the information about build failures. + +== Reminder: Building modules + +include::{partialsdir}/submit-module-build.adoc[] + +However, in this scenario, we expect your build failed. + +== Inspecting build failures + +Run the following command using the BUILD_ID from the previous step: + +---- +$ fedpkg module-build-info BUILD_ID +---- + +which shows you "State Reason" — a short summary of the build failure regarding the whole module, as well as a list of individual packages in the module. Find the ones that failed and go to the "Koji Task" URL. There, click on the "Build" link which gets you to the module build page. On this page, inspect the `root.log`, `build.log`, and other files to get the build error. \ No newline at end of file diff --git a/modules/ROOT/pages/making-modules/managing-defaults.adoc b/modules/ROOT/pages/making-modules/managing-defaults.adoc new file mode 100644 index 0000000..173d83f --- /dev/null +++ b/modules/ROOT/pages/making-modules/managing-defaults.adoc @@ -0,0 +1,14 @@ += Managing module defaults in Fedora + +Setting or changing a *default stream* or a *default installation profile* of a module is in most cases similar to changing a major version of a package. Setting or changing the default stream or the default installation profile requires a Fedora Change request, and it is only allowed in between Fedora releases. + +== Setting or changing a default + +Submit an issue to Fedora Releng in https://pagure.io/releng/issues[pagure.io/releng]. You also need to https://fedoraproject.org/wiki/Changes/Policy#For_developers[submit a Fedora Change]. + +To check the current defaults, have a look at the https://pagure.io/releng/fedora-module-defaults[fedora module defaults repository]. + +Setting or changing default stream of a module will be considered based on the following rules: + +* If the module stream does not mask any part of the Traditional RPM repos, it may be set as a default stream. For example, any module that is entirely a leaf or one that fulfills the function of a package moved from the traditional repos into the modular repos (e.g. `nodejs:8` might replace the `nodejs` traditional package) +* If the module stream masks part of the Traditional RPM repos (e.g it replaces an existing RPM or it introduces a non-trivial set of conflicts) it may not be made a default stream without the express permission of FESCo. Release engineering will be responsible for escalating any PR that is questionable on this point to FESCo for a final decision. \ No newline at end of file diff --git a/modules/ROOT/pages/making-modules/updating-modules.adoc b/modules/ROOT/pages/making-modules/updating-modules.adoc new file mode 100644 index 0000000..c1f516d --- /dev/null +++ b/modules/ROOT/pages/making-modules/updating-modules.adoc @@ -0,0 +1,46 @@ += Updating modules in Fedora + +This page will guide you through the process of updating an existing module. + +== Step 1: Update your RPM packages + +**Goal**: Get updates for your PRM packages pushed into the Fedora Distribution Git (dist-git). + +=== Workflow Summary: + +1. Make changes to your RPM package sources. +2. Push your RPM package sources to dist-git. + +=== Details: + +Useful resources: + +* https://fedoraproject.org/wiki/Packaging:Guidelines[Fedora Packaging Guidelines] +* https://fedoraproject.org/wiki/Package_maintenance_guide[Fedora Package Maintenance Guide] + +== Step 2: Bump the module version + +**Goal**: Get your module definition describing the new version pushed into the Fedora Distribution Git (dist-git). This needs to be done even when the modulemd doesn't change. + +=== Workflow Summary: + +1. Push an empty commit to your module dist-git repository. + +=== Details: + +The version of your module is taken from the last commit timestamp. Therefore, in order to submit a new module build, you need to make a new commit. To push an empty commit to your modulemd, run: + +---- +$ fedpkg clone modules/nodejs +$ cd nodejs +$ git commit --allow-empty -m "update" +$ git push +---- + +== Step 3: Build your module + +include::{partialsdir}/submit-module-build.adoc[] + +== Step 4: Make your module available to users + +include::{partialsdir}/submit-module-update.adoc[] \ No newline at end of file diff --git a/modules/ROOT/pages/references.adoc b/modules/ROOT/pages/references.adoc new file mode 100644 index 0000000..98f7eae --- /dev/null +++ b/modules/ROOT/pages/references.adoc @@ -0,0 +1,19 @@ += References + +https://pagure.io/modulemd[Module metadata definitions (modulemd)]:: + A modulemd file is used to define a module, and also to provide metadata for the end result. This is a specification of the file. + We are currently on version 1 of the specification with version 2 due very soon. + +https://pagure.io/modularity/issues[General issue tracker for Modularity]:: + General issues that are tracked here. + +https://pagure.io/group/modularity[Modularity on Pagure]:: + Pagure is the default place for most of our git repositories. + +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/modules/ROOT/pages/using-modules.adoc b/modules/ROOT/pages/using-modules.adoc new file mode 100644 index 0000000..41c9876 --- /dev/null +++ b/modules/ROOT/pages/using-modules.adoc @@ -0,0 +1,62 @@ += Using Modules in Fedora + +++++ + +++++ + +From the user perspective, modules are like release-independent package groups on independent lifecycles, providing alternative streams of content to Fedora. + +== Enable modular repositories + +If you are running the Fedora Server Edition, the Modular Repository should already be enabled. +However, if you are using a container or a different Edition, you need to: + + # dnf install fedora-repos-modular + +== Supported / Unsupported Package Managers + +* Supported +** dnf +** dnfdragora +* Unsupported (if unlisted, assume unsupported) +** microdnf +** PackageKit +** Gnome Software +** Apper +** Cockpit + +Using an unsupported Package Manager for *any* reason with modules enabled has serious potential to break things. +People are working on the above list of Unsupported package managers primarily by including module support in libdnf. +If you are interested in adding module support to a different package manager, please contact the https://github.com/rpm-software-management/dnf[dnf team]. + +== List available modules + +To list all available modules and their streams, run the following command: + + $ dnf module list + +== Install a module + +To install a module, use the `name:stream/profile` syntax, for example: + + $ dnf module install nodejs:6/default + +Alternatively, you can also enable a module and then install RPM packages directly: + + $ dnf module enable nodejs:6 + $ dnf install nodejs + +== Changing a stream + +To change a stream of a module that has been already installed, use the installation command. For example: + + $ dnf module install nodejs:9/default + +== Module defaults + +We are currently working on _system profiles_ — the defaults for your system. +Thanks to these, you will need to be specific about the module, stream, or profile only when you need to. When implemented, all the following commands will also work: + + $ dnf install nodejs # installs a nodejs RPM package from the default stream + $ dnf module install nodejs # installs the default profile from the default stream + $ dnf module install nodejs:9 # installs the default profile from the 9 stream diff --git a/preview.sh b/preview.sh new file mode 100755 index 0000000..acab783 --- /dev/null +++ b/preview.sh @@ -0,0 +1,18 @@ +#!/bin/sh + +if [ "$(uname)" == "Darwin" ]; then + # Running on macOS. + # Let's assume that the user has the Docker CE installed + # which doesn't require a root password. + echo "The preview will be available at http://localhost:8080/" + docker run --rm -v $(pwd)/public:/usr/share/nginx/html:ro -p 8080:80 nginx + +elif [ "$(expr substr $(uname -s) 1 5)" == "Linux" ]; then + # Running on Linux. + # Let's assume that it's running the Docker deamon + # which requires root. + echo "" + echo "This build script is using Docker to run the build in an isolated environment. You might be asked for a root password in order to start it." + echo "The preview will be available at http://localhost:8080/" + sudo docker run --rm -v $(pwd)/public:/usr/share/nginx/html:ro -p 8080:80 nginx +fi diff --git a/site.yml b/site.yml new file mode 100644 index 0000000..96b79fd --- /dev/null +++ b/site.yml @@ -0,0 +1,20 @@ +site: + title: Local Preview + start_page: pizza-factory::index +content: + sources: + - url: . + branches: HEAD +ui: + bundle: + url: https://asamalik.fedorapeople.org/ui-bundle.zip + snapshot: true + default_layout: with_menu +output: + clean: true + dir: ./public + destinations: + - provider: archive +runtime: + pull: true + cache_dir: ./cache From 968fd11fa686b284a911853c7eb4d7a76d9ab183 Mon Sep 17 00:00:00 2001 From: Adam Samalik Date: Jul 27 2018 12:46:09 +0000 Subject: [PATCH 2/2] fix the local preview --- diff --git a/site.yml b/site.yml index 96b79fd..7f5113f 100644 --- a/site.yml +++ b/site.yml @@ -1,6 +1,6 @@ site: title: Local Preview - start_page: pizza-factory::index + start_page: modularity::index content: sources: - url: .