From 595710418f4707e88640831f04cddb4b7051e29a Mon Sep 17 00:00:00 2001 From: Adam Samalik Date: Sep 09 2019 11:22:58 +0000 Subject: restructure the menu --- diff --git a/modules/ROOT/nav.adoc b/modules/ROOT/nav.adoc index 54a75ef..a789319 100644 --- a/modules/ROOT/nav.adoc +++ b/modules/ROOT/nav.adoc @@ -1,13 +1,16 @@ +* **What is Modularity:** +* xref:index.adoc[Quick Introduction] * xref:architecture.adoc[Architecture] ** xref:architecture/building.adoc[Building Software] ** xref:architecture/consuming.adoc[Consuming Software] -*** xref:architecture/consuming/dnf-behavior.adoc[DNF Behavior] -*** xref:architecture/consuming/upgrade-paths.adoc[Upgrade Paths] -** xref:architecture/building/name-and-id.adoc[Module name and ID] -*** xref:architecture/consuming/naming-policy.adoc[Naming Policy] -*** xref:architecture/module-version-prefix.adoc[Version Prefix] ** xref:architecture/stream-expansion.adoc[Stream Expansion] -* xref:making-modules.adoc[Making Modules] +** xref:architecture/consuming/upgrade-paths.adoc[Upgrade Paths] + +* **Basic usage:** +* xref:using-modules.adoc[Using Modules] +** xref:installing-modules.adoc[Installation and Discovery] +** xref:using-modules-switching-streams.adoc[Switching Streams] +* xref:making-modules.adoc[Making Modules — Guides] ** xref:making-modules/adding-new-modules.adoc[Adding New Modules] ** xref:making-modules/updating-modules.adoc[Updating Existing Modules] ** xref:making-modules/defining-modules.adoc[Defining Modules in modulemd] @@ -15,13 +18,28 @@ ** xref:making-modules/managing-defaults.adoc[Managing Defaults] ** xref:making-modules/inspecting-build-failures.adoc[Inspecting Build Failures] ** xref:making-modules/building-modules-locally.adoc[Building Modules Locally] -** xref:making-modules/packaging-guidelines.adoc[Packaging Guidelines] -** xref:making-modules/naming-guidelines.adoc[Naming Guidelines] -* xref:hosting-modules.adoc[Hosting Modules] -* xref:using-modules.adoc[Using Modules] -* xref:community.adoc[Community] -** xref:community/teams.adoc[Teams and Working Groups] -** xref:community/project-tracking.adoc[Project tracking] -** xref:reporting-issues.adoc[Reporting issues] +* xref:making-modules-policies.adoc[Making Modules — Policies] +** xref:making-modules/packaging-guidelines.adoc[Packaging Policy] +** xref:making-modules/naming-guidelines.adoc[Naming Policy] +* xref:reporting-module-bugs.adoc[Reporting Module Bugs] * xref:faq.adoc[FAQ] -* xref:references.adoc[References] \ No newline at end of file + +* **Advanced:** +* xref:hosting-modules.adoc[Creating Modular Repositories] +* xref:using-other-build-systems.adoc[Using Other Build Systems] +* xref:architecture/building/name-and-id.adoc[NSVCA (Module ID)] +** xref:architecture/module-version-prefix.adoc[Version Prefix] +** xref:architecture/consuming/naming-policy.adoc[NSVCA Definition] + +* **Community:** +* xref:community.adoc[Communication] +* xref:community/teams.adoc[Teams and Working Groups] +* xref:community/project-tracking.adoc[Project Tracking] +* xref:reporting-issues.adoc[Reporting Project Issues] + +* **Other:** +* xref:references.adoc[References] +* xref:archive.adoc[Archive] +** xref:architecture/consuming/dnf-behavior.adoc[DNF Behavior] + + diff --git a/modules/ROOT/pages/architecture.adoc b/modules/ROOT/pages/architecture.adoc index 2623bd6..ea121a1 100644 --- a/modules/ROOT/pages/architecture.adoc +++ b/modules/ROOT/pages/architecture.adoc @@ -1,4 +1,6 @@ -= Main Concepts of Modularity += Modularity Architecture + +NOTE: This page needs to be rewritten Modularity reuses some existing and creates some new concepts in the build and release process in Fedora. diff --git a/modules/ROOT/pages/architecture/consuming/dnf-behavior.adoc b/modules/ROOT/pages/architecture/consuming/dnf-behavior.adoc index 8bf6068..0221220 100644 --- a/modules/ROOT/pages/architecture/consuming/dnf-behavior.adoc +++ b/modules/ROOT/pages/architecture/consuming/dnf-behavior.adoc @@ -1,5 +1,7 @@ = Modular DNF Behavior +WARNING: This page has been archived. It contains information that is either no longer true, relevant, or it should not be part of this documentation. It has been kept for historical reasons and can be removed at any time. + This page captures the key behaviors of modular DNF. == Definitions diff --git a/modules/ROOT/pages/architecture/consuming/naming-policy.adoc b/modules/ROOT/pages/architecture/consuming/naming-policy.adoc index c0c49cd..8e49c27 100644 --- a/modules/ROOT/pages/architecture/consuming/naming-policy.adoc +++ b/modules/ROOT/pages/architecture/consuming/naming-policy.adoc @@ -1,4 +1,4 @@ -= Naming Policy += NSVCA Definition This document defines naming policy for modulemd metadata of final (built) modules. This policy does **NOT** apply on sources such as modulemd yaml in dist-git. diff --git a/modules/ROOT/pages/archive.adoc b/modules/ROOT/pages/archive.adoc new file mode 100644 index 0000000..684560c --- /dev/null +++ b/modules/ROOT/pages/archive.adoc @@ -0,0 +1,3 @@ += Archive + +Pages in archive used to be part of the Modularity docs, but have been either moved out or retired. Some of them are still kept here for reference. \ No newline at end of file diff --git a/modules/ROOT/pages/installing-modules.adoc b/modules/ROOT/pages/installing-modules.adoc new file mode 100644 index 0000000..54cead2 --- /dev/null +++ b/modules/ROOT/pages/installing-modules.adoc @@ -0,0 +1,65 @@ += Module Installation and Discovery + +== Discovering content + +=== Listing packages + +Packages available to the system can be discovered by the usual commands such as `dnf search NAME`, `dnf list NAME`, or by using the `dnf repoquery QUERY` command for more complex queries. However, it is important to note that those commands will, apart from traditional packages, only list modular packages coming from a _default_ or an _enabled_ module stream. + +=== Listing modules + +To list modules available to your system, and to see what streams are _default_ or have been _enabled_, use the following command: + + $ dnf module list + +== Consuming content + +=== Installing packages + +Packages can be installed the usual way by running the `dnf install NAME` command. Any traditional package, or a modular package coming from a _default_ or an _enabled_ module can be installed this way. + +Packages from other module streams can be consumed by either _enabling a module_ stream and then installing individual packages, or by _installing a module_ directly. + +=== Enabling modules + +To **enable a module stream** and make its packages available for installation, run the following command: + + $ dnf module enable NAME:STREAM + +For example, to make Node.js 8 packages available for installation, run: + + $ dnf module enable nodejs:8 + +Packages from enabled module streams can be then installed by the `dnf install NAME` command. + +=== Installing modules + +To install a module, use one of the following commands. Not specifying a _stream_ or a _profile_ causes DNF to choose the _default_. However, not every module has a _default stream_ or _default profile_. + + $ dnf module install NAME + $ dnf module install NAME:STREAM + $ dnf module install NAME/PROFILE + $ dnf module install NAME:STREAM/PROFILE + +For example, to install the Node.js 8 runtime and the client tooling of the default stream of MongoDB, run: + + $ dnf module install nodejs:8 + $ dnf module install mongodb/client + +=== Switching module streams + +NOTE: Switching streams is a risky operation that might not be always supported in packages, especially downgrades. + +Switching to a different stream than the one that is installed on a system is a two-step process. First, the current stream needs to be reset causing it not to be enabled anymore — this will however keep its packages installed. Second, a new stream needs to be installed. + + $ dnf module reset NAME + $ dnf module install NAME:STREAM + +For example, to switch from Node.js 8 to Node.js 10, run: + + $ dnf module reset nodejs + $ dnf module install nodejs:10 + +== Updating the system + +Updating a system by running the `dnf update` command causes all packages to be upgraded to their latest version provided by their module stream. \ No newline at end of file diff --git a/modules/ROOT/pages/making-modules-policies.adoc b/modules/ROOT/pages/making-modules-policies.adoc new file mode 100644 index 0000000..2c171c7 --- /dev/null +++ b/modules/ROOT/pages/making-modules-policies.adoc @@ -0,0 +1,3 @@ += Policies Regarding Modules in Fedora + +NOTE: This page needs to be written \ No newline at end of file diff --git a/modules/ROOT/pages/reporting-module-bugs.adoc b/modules/ROOT/pages/reporting-module-bugs.adoc new file mode 100644 index 0000000..69def59 --- /dev/null +++ b/modules/ROOT/pages/reporting-module-bugs.adoc @@ -0,0 +1,5 @@ += Reporting Module Bugs + +NOTE: This page needs to be written + +Bugs against Fedora modules are reported in http://bugzilla.redhat.com[Bugzilla]. \ No newline at end of file diff --git a/modules/ROOT/pages/using-modules-switching-streams.adoc b/modules/ROOT/pages/using-modules-switching-streams.adoc new file mode 100644 index 0000000..1c45990 --- /dev/null +++ b/modules/ROOT/pages/using-modules-switching-streams.adoc @@ -0,0 +1,33 @@ += Switching module streams + +NOTE: This page needs to be extended. + +NOTE: Switching streams is a risky operation that might not be always supported in packages, especially downgrades. + +Switching to a different stream than the one that is installed on a system is a two-step process. First, the current stream needs to be reset causing it not to be enabled anymore — this will however keep its packages installed. Second, a new stream needs to be installed. + + $ sudo dnf module reset NAME + $ sudo dnf module install NAME:STREAM + +For example, to switch from Node.js 8 to Node.js 10, run: + + $ sudo dnf module reset nodejs + $ sudo dnf module install nodejs:10 + +When switching RPMs that are not in a profile of stream, that is a three step process. First, the current stream needs to be reset. Second, a new stream needs to be enabled. Three, the specified RPMs are synchronized on the new stream. + + $ sudo dnf module reset NAME + $ sudo dnf module enable NAME:STREAM + $ sudo dnf --allowerasing distro-sync [RPM]... + +For example, to switch installed RPMs from Ruby 2.5 to Ruby 2.6, run: + + $ sudo dnf module reset ruby + $ sudo dnf module enable ruby:2.6 + $ sudo dnf --allowerasing distro-sync + +To switch specified RPMs rubygem-mysql2 and rubygem-pg from Ruby 2.5 to Ruby 2.6, run: + + $ sudo dnf --allowerasing distro-sync rubygem-mysql2 rubygem-pg + +HINT: `dnf module info NAME:STREAM` Artifacts is helpful to check RPMs in a module. \ No newline at end of file diff --git a/modules/ROOT/pages/using-modules.adoc b/modules/ROOT/pages/using-modules.adoc index 9e567a0..937caaf 100644 --- a/modules/ROOT/pages/using-modules.adoc +++ b/modules/ROOT/pages/using-modules.adoc @@ -10,84 +10,5 @@ And because having too many choices might be overwhelming, Fedora ships with a s Finally, because big changes are not always welcome, Modularity has been built in a way it can be basically invisible to the user. The usual installation commands continue to work — so packages with a default stream can be installed the same way as before regardles of them being modularized or not. -== Discovering content +Coninue to the xref:installing-modules.adoc[Installation and Discovery] page to learn about the actual commands. -=== Listing packages - -Packages available to the system can be discovered by the usual commands such as `dnf search NAME`, `dnf list NAME`, or by using the `dnf repoquery QUERY` command for more complex queries. However, it is important to note that those commands will, apart from traditional packages, only list modular packages coming from a _default_ or an _enabled_ module stream. - -=== Listing modules - -To list modules available to your system, and to see what streams are _default_ or have been _enabled_, use the following command: - - $ dnf module list - -== Consuming content - -=== Installing packages - -Packages can be installed the usual way by running the `dnf install NAME` command. Any traditional package, or a modular package coming from a _default_ or an _enabled_ module can be installed this way. - -Packages from other module streams can be consumed by either _enabling a module_ stream and then installing individual packages, or by _installing a module_ directly. - -=== Enabling modules - -To **enable a module stream** and make its packages available for installation, run the following command: - - $ sudo dnf module enable NAME:STREAM - -For example, to make Node.js 8 packages available for installation, run: - - $ sudo dnf module enable nodejs:8 - -Packages from enabled module streams can be then installed by the `dnf install NAME` command. - -=== Installing modules - -To install a module, use one of the following commands. Not specifying a _stream_ or a _profile_ causes DNF to choose the _default_. However, not every module has a _default stream_ or _default profile_. - - $ sudo dnf module install NAME - $ sudo dnf module install NAME:STREAM - $ sudo dnf module install NAME/PROFILE - $ sudo dnf module install NAME:STREAM/PROFILE - -For example, to install the Node.js 8 runtime and the client tooling of the default stream of MongoDB, run: - - $ sudo dnf module install nodejs:8 - $ sudo dnf module install mongodb/client - -=== Switching module streams - -NOTE: Switching streams is a risky operation that might not be always supported in packages, especially downgrades. - -Switching to a different stream than the one that is installed on a system is a two-step process. First, the current stream needs to be reset causing it not to be enabled anymore — this will however keep its packages installed. Second, a new stream needs to be installed. - - $ sudo dnf module reset NAME - $ sudo dnf module install NAME:STREAM - -For example, to switch from Node.js 8 to Node.js 10, run: - - $ sudo dnf module reset nodejs - $ sudo dnf module install nodejs:10 - -When switching RPMs that are not in a profile of stream, that is a three step process. First, the current stream needs to be reset. Second, a new stream needs to be enabled. Three, the specified RPMs are synchronized on the new stream. - - $ sudo dnf module reset NAME - $ sudo dnf module enable NAME:STREAM - $ sudo dnf --allowerasing distro-sync [RPM]... - -For example, to switch installed RPMs from Ruby 2.5 to Ruby 2.6, run: - - $ sudo dnf module reset ruby - $ sudo dnf module enable ruby:2.6 - $ sudo dnf --allowerasing distro-sync - -To switch specified RPMs rubygem-mysql2 and rubygem-pg from Ruby 2.5 to Ruby 2.6, run: - - $ sudo dnf --allowerasing distro-sync rubygem-mysql2 rubygem-pg - -HINT: `dnf module info NAME:STREAM` Artifacts is helpful to check RPMs in a module. - -== Updating the system - -Updating a system by running the `dnf update` command causes all packages to be upgraded to their latest version provided by their module stream. diff --git a/modules/ROOT/pages/using-other-build-systems.adoc b/modules/ROOT/pages/using-other-build-systems.adoc new file mode 100644 index 0000000..442810b --- /dev/null +++ b/modules/ROOT/pages/using-other-build-systems.adoc @@ -0,0 +1,3 @@ += Using Other Build System with Modularity + +NOTE: This page needs to be written.