PR#68: New menu structure proposal - fedora-docs/modularity

fedora-docs / modularity

#68 New menu structure proposal

Merged 4 years ago by asamalik. Opened 4 years ago by asamalik.

fedora-docs/ asamalik/modularity restructure into master

restructure the menu

Adam Samalik • 4 years ago

5957104

modules/ROOT/nav.adoc

file modified

+33 -15

		`@@ -1,13 +1,16 @@`
		`+ * What is Modularity:`
		`+ * xref:index.adoc[Quick Introduction]`
langdon commented 4 years ago how about "intro" which will make it less formal (and "quick start" doesn't make sense)
		`* xref:architecture.adoc[Architecture]`
langdon commented 4 years ago i think this should go under "advanced" it is still to "top level"
		`** 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:`
langdon commented 4 years ago how about "basic modularity" or "Common" .. i don't like "basic usage" when talking about "building modules" and in comparison to just "advanced"
		`+ * 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]`
langdon commented 4 years ago this needs the "this needs a rewrite" sticker.. the meeting info is wrong
		`- ** xref:community/teams.adoc[Teams and Working Groups]`
langdon commented 4 years ago we should probably add mbs and dnf upstreams here
		`- ** 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]`
langdon commented 4 years ago I wonder if a FAQ under "making modules" would make sense .. like tips about making them.. not sure if a faq under "using" also makes sense
		`- * xref:references.adoc[References]`
		`\ No newline at end of file`
		`+`
		`+ * Advanced:`
langdon commented 4 years ago can this collapse? and start closed?
		`+ * 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]`
		`+`
		`+`

modules/ROOT/pages/architecture.adoc

file modified

+3 -1

		`@@ -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.`

modules/ROOT/pages/architecture/consuming/dnf-behavior.adoc

file modified

		`@@ -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`

modules/ROOT/pages/architecture/consuming/naming-policy.adoc

file modified

+1 -1

		`@@ -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.`

modules/ROOT/pages/archive.adoc

file added

		`@@ -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`

modules/ROOT/pages/installing-modules.adoc

file added

+65

		`@@ -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`

modules/ROOT/pages/making-modules-policies.adoc

file added

		`@@ -0,0 +1,3 @@`
		`+ = Policies Regarding Modules in Fedora`
		`+`
		`+ NOTE: This page needs to be written`
		`\ No newline at end of file`

modules/ROOT/pages/reporting-module-bugs.adoc

file added

		`@@ -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`

modules/ROOT/pages/using-modules-switching-streams.adoc

file added

+33

		`@@ -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`

modules/ROOT/pages/using-modules.adoc

file modified

+1 -80

		`@@ -10,84 +10,5 @@`

		`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.

modules/ROOT/pages/using-other-build-systems.adoc

file added

		`@@ -0,0 +1,3 @@`
		`+ = Using Other Build System with Modularity`
		`+`
		`+ NOTE: This page needs to be written.`

asamalik commented 4 years ago

I propose a new menu structure for the Modularity Docs to make the content more discoverable. I haven't done any actual content changes with this PR, only a lot of reshuffling.

As this is a rather big change, here's a preview: https://asamalik.fedorapeople.org/modularity-docs-restructure/modularity/

rebased onto 5957104

4 years ago

asamalik commented 4 years ago

@psabata @langdon @sgallagh This is the change we've talked about. Let me know what you think! :)

asamalik commented 4 years ago

All right, I think I'll give you two more days and then I'll just merge it. :-)

langdon commented on line 3 of modules/ROOT/nav.adoc 4 years ago

how about "intro" which will make it less formal (and "quick start" doesn't make sense)

langdon commented on line 4 of modules/ROOT/nav.adoc 4 years ago

i think this should go under "advanced" it is still to "top level"

langdon commented on line 40 of modules/ROOT/nav.adoc 4 years ago

I wonder if a FAQ under "making modules" would make sense .. like tips about making them.. not sure if a faq under "using" also makes sense

langdon commented on line 32 of modules/ROOT/nav.adoc 4 years ago

this needs the "this needs a rewrite" sticker.. the meeting info is wrong

langdon commented on line 33 of modules/ROOT/nav.adoc 4 years ago

we should probably add mbs and dnf upstreams here

langdon commented on line 44 of modules/ROOT/nav.adoc 4 years ago

can this collapse? and start closed?

langdon commented on line 16 of modules/ROOT/nav.adoc 4 years ago

how about "basic modularity" or "Common" .. i don't like "basic usage" when talking about "building modules" and in comparison to just "advanced"

langdon commented 4 years ago

oh.. i forgot how pagure worked with comments like this.. ick.. well.. i gave some feedback :/

asamalik commented 4 years ago

@langdon Thanks for the feedback!

oh.. i forgot how pagure worked with comments like this.. ick.. well.. i gave some feedback :/

Heh, yeah, I won't even try to respond to the individual things. :)

But I agree with most of the cosmetic changes.

Good point with a special FAQ for creating modules — we can definitely make sections in FAQ.

My thinking behind including "Architecture" under the "What is Modularity" section is that people should know what a module, a stream, etc. are before they can do anything with it. So maybe simplifying that, and possibly including a deep dive under "Advanced" would be an option?

asamalik commented 4 years ago

We've just discussed this with @langdon and @psabata and decided to merge this and continue in additional PRs.

Pull-Request has been merged by asamalik

4 years ago