Software-Management #969

goroboro · 2026-05-11T13:12:45Z

goroboro commented

2026-05-11 13:12:45 +00:00

This PR significantly overhauls the "Adding and managing software" section of Fedora Quick Docs, bringing it up to date for currently supported releases (Fedora 41 and newer, using DNF5) and restructuring the navigation for clarity.

Navigation restructure

The section is reorganised into three clear areas: core package management topics, a third-party software subsection, and a new "Installing popular applications" group. Topics covering specific applications (VLC, Spotify, Zoom, Chromium, Java, fonts, desktop environments) are grouped separately from package management mechanics. openh264.adoc is retired and its content is merged into the multimedia plugins page. Also, I separated out legal content and put that under the FAQ section and did away with the remaining content in packagekit-not-found.adoc because this was consolidated into some newer topics described below.

New topics

I added several new topics:

Third-party software: overview of the distinction between Fedora release software and third-party sources, why software may be absent (patents, licensing, unpackaged), and safe usage practices
Flatpak / Flathub: installing and managing Flatpak applications, covering both GNOME Software and KDE Discover
Snap Store: installing and managing Snap applications
AppImage: running portable AppImage applications
Language package managers: pip, npm, Cargo, gem, and go install, with emphasis on isolation (virtual environments) and the preference for Fedora-packaged versions
~~Managing software on immutable Fedora editions: rpm-ostree layering, Flatpak as the preferred app delivery method, and Toolbox for development environments~~
Creating a DNF repository mirror: using dnf reposync to set up a local mirror, serving it with Apache, configuring clients, and keeping it current with a systemd timer
Fedora and software patents: split out from the retired packagekit-not-found.adoc into its own FAQ topic

Updated topics

autoupdates.adoc: restructured (decision first, setup second), dnf-automatic.timer updated for DNF5 (single timer replaces the old per-mode timers), machine → system throughout, auter section retained and updated
package-management.adoc: rewritten to be a concise intro rather than a stub with broken links
securing-the-system-by-keeping-it-up-to-date.adoc: recommends dnf offline-upgrade over updating a live system; redundant automatic updates section replaced with an xref to autoupdates.adoc
installing-java.adoc: Java version updated (LTS: 21, 25; latest: 26); JDK components list pruned of tools removed in JDK 9–14; modern tools added (jshell, jlink, jpackage, jdeps, jhsdb); dead links fixed (Freenode → Libera.Chat, Mailman → Fedora Discussion, openjdk.java.net → openjdk.org)
installing-plugins-for-playing-movies-and-music.adoc: updated for F41+; OpenH264 content merged in; RPM Fusion noted for extended codec support; immutable editions section added; Fedora Workstation multimedia group updated
installing-chromium-or-google-chrome-browsers.adoc: DNF4 old-syntax block removed; chromium-freeworld from RPM Fusion noted for users needing full codec support; screenshots updated for current GNOME Software and Plasma Discover UI
fonts.adoc: rewritten for current Fedora; GNOME Font Viewer bug note removed; KDE section updated for Plasma 6; RPM Fusion font source note corrected; code block formatting fixed
finding-and-installing-linux-applications.adoc: repository overview section removed (now links to dedicated topics); GNOME and KDE GUI walkthroughs updated with fresh screenshots on Fedora 42 with GNOME 50 and Plasma 6; category descriptions corrected to match actual UI
switching-desktop-environments.adoc : renamed "Installing and Switching Desktop Environments"; updated for Fedora 41+ (single dnf environment list command) --- worth noting that although I could install switchdesk it didn't really work properly in my test lab.
fedora-and-software-patents.adoc: dead links removed (Fluendo, 2007–2010 Red Hat press releases, old mailing list); MP3 no longer referenced as patent-encumbered (patents expired 2017)

Style and consistency pass

All topics in the section were run through the Red Hat Vale linter. Changes include: contractions expanded, passive voice reduced, heading capitalisation normalised (sentence case for H2+), code blocks annotated with [source,bash,console] and / sudo prompts, e.g./i.e. replaced with for example/that is, and Fedora-specific vocabulary added to the Vale exceptions file.

Screenshots

All screenshots in finding-and-installing-linux-applications.adoc are retaken on Fedora 42 (GNOME 50 and Plasma 6), replacing images from the older Fedora releases.

This PR significantly overhauls the "Adding and managing software" section of Fedora Quick Docs, bringing it up to date for currently supported releases (Fedora 41 and newer, using DNF5) and restructuring the navigation for clarity. *Navigation restructure* The section is reorganised into three clear areas: core package management topics, a third-party software subsection, and a new "Installing popular applications" group. Topics covering specific applications (VLC, Spotify, Zoom, Chromium, Java, fonts, desktop environments) are grouped separately from package management mechanics. openh264.adoc is retired and its content is merged into the multimedia plugins page. Also, I separated out legal content and put that under the FAQ section and did away with the remaining content in packagekit-not-found.adoc because this was consolidated into some newer topics described below. *New topics* I added several new topics: - Third-party software: overview of the distinction between Fedora release software and third-party sources, why software may be absent (patents, licensing, unpackaged), and safe usage practices - Flatpak / Flathub: installing and managing Flatpak applications, covering both GNOME Software and KDE Discover - Snap Store: installing and managing Snap applications - AppImage: running portable AppImage applications - Language package managers: pip, npm, Cargo, gem, and go install, with emphasis on isolation (virtual environments) and the preference for Fedora-packaged versions - ~~Managing software on immutable Fedora editions: rpm-ostree layering, Flatpak as the preferred app delivery method, and Toolbox for development environments~~ - Creating a DNF repository mirror: using dnf reposync to set up a local mirror, serving it with Apache, configuring clients, and keeping it current with a systemd timer - Fedora and software patents: split out from the retired packagekit-not-found.adoc into its own FAQ topic *Updated topics* - autoupdates.adoc: restructured (decision first, setup second), dnf-automatic.timer updated for DNF5 (single timer replaces the old per-mode timers), machine → system throughout, auter section retained and updated - package-management.adoc: rewritten to be a concise intro rather than a stub with broken links - securing-the-system-by-keeping-it-up-to-date.adoc: recommends dnf offline-upgrade over updating a live system; redundant automatic updates section replaced with an xref to autoupdates.adoc - installing-java.adoc: Java version updated (LTS: 21, 25; latest: 26); JDK components list pruned of tools removed in JDK 9–14; modern tools added (jshell, jlink, jpackage, jdeps, jhsdb); dead links fixed (Freenode → Libera.Chat, Mailman → Fedora Discussion, openjdk.java.net → openjdk.org) - installing-plugins-for-playing-movies-and-music.adoc: updated for F41+; OpenH264 content merged in; RPM Fusion noted for extended codec support; immutable editions section added; Fedora Workstation multimedia group updated - installing-chromium-or-google-chrome-browsers.adoc: DNF4 old-syntax block removed; chromium-freeworld from RPM Fusion noted for users needing full codec support; screenshots updated for current GNOME Software and Plasma Discover UI - fonts.adoc: rewritten for current Fedora; GNOME Font Viewer bug note removed; KDE section updated for Plasma 6; RPM Fusion font source note corrected; code block formatting fixed - finding-and-installing-linux-applications.adoc: repository overview section removed (now links to dedicated topics); GNOME and KDE GUI walkthroughs updated with fresh screenshots on Fedora 42 with GNOME 50 and Plasma 6; category descriptions corrected to match actual UI - switching-desktop-environments.adoc : renamed "Installing and Switching Desktop Environments"; updated for Fedora 41+ (single dnf environment list command) --- worth noting that although I could install switchdesk it didn't really work properly in my test lab. - fedora-and-software-patents.adoc: dead links removed (Fluendo, 2007–2010 Red Hat press releases, old mailing list); MP3 no longer referenced as patent-encumbered (patents expired 2017) *Style and consistency pass* All topics in the section were run through the Red Hat Vale linter. Changes include: contractions expanded, passive voice reduced, heading capitalisation normalised (sentence case for H2+), code blocks annotated with [source,bash,console] and $/$ sudo prompts, e.g./i.e. replaced with for example/that is, and Fedora-specific vocabulary added to the Vale exceptions file. *Screenshots* All screenshots in finding-and-installing-linux-applications.adoc are retaken on Fedora 42 (GNOME 50 and Plasma 6), replacing images from the older Fedora releases.

goroboro added 29 commits

2026-05-11 13:12:45 +00:00

Remove old Fedora (dnf4) instructions and avoid specifying yum in references to software repositories. acdfb96c3b

#923

Added a general topic on Third Party Software so that we can regroup content about third party software under this topic to keep it separated from main Fedora content. It is still useful to users, but helps to delineate between what is actually supported and part of the distribution, and what comes from outside. a89e871ee6

Add credits and correct date affa36bd2d

Add topic on using AppImages to install third party software 99cd0484e0

Add a topic on Flatpak 607aab95f9

Add a topic on snaps for third party software 247546e15e

Add coverage for language package managers bbf3e328a9

Improved phrasing around dnf-automatic timer options. The previously distinct timer units were merged and are no longer relevant to a current release. 45a6c3cd15

Overhaul of the Java quickdoc. The latest version of Java is 26. 5e372e8771

Many of the install instructions included the system arch which was unnecessary and made the instructions arch specific.
The component list was outdated with many components no longer maintained or no longer relevant or superceded.
IcedTea is no longer maintained.
Fixed various broken links.

Update the securing the system topic to remove the redundant automatic updates section and to xref into the existing topic. Also recommend offline updates per #923 51759f16a8

Fix revnumber to reference currently supported versions, since all of these topics were created aftrer 41 went EOL bdc969ce6f

We need to cover how to manage software on immutable editions a91295c9ff

Update install content around Installing plugins for playing movies and music. Group install only needs to cover from Fedora 42 onward, so this is a cleaner instruction. 26a1b3fa7e

Added mention on extending codec support through RPM Fusion and provided an xref for this.
Merge content on openh264 and remove old irrelevant content for openh264. Validate instructions for Firefox.

Change title of switching-desktop-environments to include the word installing, so that it makes sense in the context of Software Management, otherwise this topic looks out of place. a842d011f6

Also dnf environment list is available in Fedora 41, so we only need one command for this.

Add topics to nav for adding and managing software. Reorganize nav to provide better separation between actual software management topics, third party software tooling, and installing popular applications. a040cb5fa7

Fix accidental page aliases... that make no sense 685b05a230

Remove the packagekit topic because it had lots of broken, outdated and missing self-referential links. Separate out the content on patents etc and move that to the FAQ section. Also add a more generic entry to the third party software topic to explain why some software is missing - often because of patents and licensing terms. 87b02993c1

Update package management doc to become more introductory to the rest of the topic area and to remove mention of PackageKit which was just incorrect anyway, because this doesn't provide a GUI to package management, but rather a dbus interface used by other tooling. This information isn't really helpful to most users. fa1cbff099

More reordering of topics to try to make this more coherent and cohesive 7db6e4da19

Add a topic on DNF mirrors. 3b3442cf65

Improve the writeup around dnf automatic and remove obsolete information about iptables etc as this is replaced with nftables. Just made this content tighter and more focused. 21af9cb34a

Restructure further to move dnf-vs-apt under DNF, and then add in the mirroring topic 03f11330ba

Improve codeblocks. Use sudo where the user needs to be root, use the console class so that the $ doesn't get copied during a copy/paste operation a9cbb11ca3

Topics are all updated for vale feedback 27ef37cb1b

Update fonts for plasma 6 and to improve wording and validate fa24185524

Update the Google Chrome instructions and screenshots 07f60c4d66

I accidentally nuked content in switching desktops. Fixed. Important note: The switchdesktop command doesn't seem to work so well in Fedora 44, may need further testing. fb0a205fe2

Redo screenshots and update the content to match more recent releases of these Desktop Environments. Also reduce discussion about repositories and just link to topics that discuss this at length. 4452b0d54c

Slight rework of content to match screenshots f39745f0fa

hricky reviewed

2026-05-11 15:43:54 +00:00

modules/ROOT/pages/dnf.adoc Outdated

					
				@ -15,6 +15,8 @@ DNF makes it easy to maintain packages by automatically checking for dependencie

				This method eliminates the need to manually install or update the package, and its dependencies, using the `rpm` command.

				DNF is now the default software package management tool in Fedora.

				NOTE: DNF applies to standard Fedora editions. On immutable editions such as Silverblue, Kinoite, and Sway Atomic, the base system is read-only and package management works differently. See xref:software-management-immutable.adoc[Managing software on immutable Fedora editions].

We prefer to call these systems image based (or image-based) rather than immutable. Also, the only image based Fedora edition currently is CoreOS. All Atomic Desktops, and also bootc images are better described as image based variants.

We prefer to call these systems _image based_ (or _image-based_) rather than _immutable_. Also, the only image based Fedora edition currently is CoreOS. All Atomic Desktops, and also bootc images are better described as _image based variants_.

Thanks for this feedback. I have gone through all of my mentions and updated. Hopefully the latest commit fixes this.

modules/ROOT/pages/software-management-immutable.adoc Outdated

					
				@ -0,0 +30,4 @@

				Flatpak is the recommended way to install desktop applications on immutable Fedora editions.

				Flatpak applications run in a sandboxed environment and do not require changes to the base system image, so no reboot is needed after installation.

				Fedora's immutable editions ship with Flatpak support and the Flathub repository configured by default.

The Flathub repository is not configured (or more precisely – enabled) by default on Atomic Desktops systems yet, but this will likely change for the F45 release. BTW, we should rework this and the whole Flatpak section in our docs.

The Flathub repository is not configured (or more precisely – _enabled_) by default on Atomic Desktops systems yet, but this will likely change for the F45 release. BTW, we should rework this and the whole Flatpak section in our docs.

I have changed this to include a statement that you need to enable the Flathub repo. Hopefully that makes sense. I don't have atomic system running to test this right now.

hricky commented

2026-05-11 16:02:43 +00:00

As a side note, submitting such a huge amount of changes and commits in a single PR makes it very hard to review, at least for me.

👍 1

hricky reviewed

2026-05-11 16:56:43 +00:00

modules/ROOT/pages/software-management-immutable.adoc Outdated

					
				@ -0,0 +132,4 @@

				$ rpm-ostree install distrobox

				----

				== Additional resources

I would recommend adding a reference to the Fedora Atomic Desktops User Guide.

Additionally, rewording immutable and editions throughout will align this page with the Atomic Desktops docs.

Also, for the AsciiDoc styling I would suggest placing every sentence on its own line and properly formatting the source code blocks (in this case console commands) for easier and more accurate copying and pasting.

I would recommend adding a reference to the [Fedora Atomic Desktops User Guide](https://docs.fedoraproject.org/en-US/atomic-desktops/). Additionally, rewording _immutable_ and _editions_ throughout will align this page with the Atomic Desktops docs. Also, for the AsciiDoc styling I would suggest placing every sentence on its own line and properly formatting the source code blocks (in this case console commands) for easier and more accurate copying and pasting.

I think I have done this accurately. Let me know if there is anything that you see missing.
Most of the content in this section of the repo didn't have the 'console' class set on any of the codeblocks. I tried to add them. Hopefully I have done this correctly.

I think I have done this accurately. Let me know if there is anything that you see missing. Most of the content in this section of the repo didn't have the 'console' class set on any of the codeblocks. I tried to add them. Hopefully I have done this correctly.

goroboro added 1 commit

2026-05-11 19:04:55 +00:00

Updates around Managing Software on Fedora Atomic Desktops - after review from hricky 1c9ea58581

goroboro commented

2026-05-11 19:11:27 +00:00

@hricky wrote in #969 (comment):

As a side note, submitting such a huge amount of changes and commits in a single PR makes it very hard to review, at least for me.

That's fair but it was a fairly hefty restructure and as I worked there were an increasing number of gaps and fixes that needed to happen. I did apologize for the scale of this in the docs Matrix channel. In future, I will try to submit smaller PRs.

@hricky wrote in https://forge.fedoraproject.org/docs/quick-docs/pulls/969#issuecomment-707890: > As a side note, submitting such a huge amount of changes and commits in a single PR makes it very hard to review, at least for me. That's fair but it was a fairly hefty restructure and as I worked there were an increasing number of gaps and fixes that needed to happen. I did apologize for the scale of this in the docs Matrix channel. In future, I will try to submit smaller PRs.

hricky commented

2026-05-11 20:56:21 +00:00

@goroboro wrote in #969 (comment):

I don't have atomic system running to test this right now.

When we write docs for image based systems, we always test what we document.

I'm not entirely sure we even need a software management page for image based systems in Quick Docs. The way this page is currently written simply repeats what's already explained in the Atomic Desktops and CoreOS docs and still needs corrections. I think if we want to mention package management for image based systems in the DNF and other pages, we can just refer to the relevant docs.

@goroboro wrote in https://forge.fedoraproject.org/docs/quick-docs/pulls/969#issuecomment-707939: > I don't have atomic system running to test this right now. When we write docs for image based systems, we always test what we document. I'm not entirely sure we even need a software management page for image based systems in Quick Docs. The way this page is currently written simply repeats what's already explained in the Atomic Desktops and CoreOS docs and still needs corrections. I think if we want to mention package management for image based systems in the DNF and other pages, we can just refer to the relevant docs.

goroboro commented

2026-05-11 21:13:29 +00:00

@hricky wrote in #969 (comment):

@goroboro wrote in #969 (comment):

I don't have atomic system running to test this right now.

When we write docs for image based systems, we always test what we document.

I'm not entirely sure we even need a software management page for image based systems in Quick Docs. The way this page is currently written simply repeats what's already explained in the Atomic Desktops and CoreOS docs and still needs corrections. I think if we want to mention package management for image based systems in the DNF and other pages, we can just refer to the relevant docs.

Okay, but I think this is true of most of the quick-docs. We could just say, this stuff repeats what is in the docs, or needs to go into the docs. Since the quick-docs has sections that describe how to do things with DNF, the omission of any mention of the atomic desktops and the fact that software management is different is confusing and misleading. I aimed to make this a bit more comprehensive and balanced.
I will spin up a VM with at least one atomic desktop to step through this.
It would help if you just let me know what corrections need to be made or what is inaccurate.
If it makes sense to drop this, then I am happy to do so, but then I would argue to drop probably around 60% of the content in quick-docs.

@hricky wrote in https://forge.fedoraproject.org/docs/quick-docs/pulls/969#issuecomment-707953: > @goroboro wrote in #969 (comment): > > > I don't have atomic system running to test this right now. > > When we write docs for image based systems, we always test what we document. > > I'm not entirely sure we even need a software management page for image based systems in Quick Docs. The way this page is currently written simply repeats what's already explained in the Atomic Desktops and CoreOS docs and still needs corrections. I think if we want to mention package management for image based systems in the DNF and other pages, we can just refer to the relevant docs. Okay, but I think this is true of most of the quick-docs. We could just say, this stuff repeats what is in the docs, or needs to go into the docs. Since the quick-docs has sections that describe how to do things with DNF, the omission of any mention of the atomic desktops and the fact that software management is different is confusing and misleading. I aimed to make this a bit more comprehensive and balanced. I will spin up a VM with at least one atomic desktop to step through this. It would help if you just let me know what corrections need to be made or what is inaccurate. If it makes sense to drop this, then I am happy to do so, but then I would argue to drop probably around 60% of the content in quick-docs.

hricky commented

2026-05-12 08:34:54 +00:00

I can't speak for Quick Docs as a whole because I haven't read every single page. As I said:

I think if we want to mention package management for image based systems in the DNF and other pages, we can just refer to the relevant docs.

These docs are maintained by the appropriate teams and we strive to keep them up-to-date and understandable for all types of readers. If we are going to add a special page in Quick Docs related to image-based systems, I think the right way is to first open an issue to discuss if adding such a page is appropriate. If we decide it is, then I can assist with writing and maintaining it.

I can't speak for Quick Docs as a whole because I haven't read every single page. As I said: > I think if we want to mention package management for image based systems in the DNF and other pages, we can just refer to the relevant docs. These docs are maintained by the appropriate teams and we strive to keep them up-to-date and understandable for all types of readers. If we are going to add a special page in Quick Docs related to image-based systems, I think the right way is to first open an issue to discuss if adding such a page is appropriate. If we decide it is, then I can assist with writing and maintaining it.

theprogram commented

2026-05-12 11:22:56 +00:00

Linking to authoritative content and deduplication are really important.

To note, @hricky is a leader in the Atomic distro space, so his words here carry a lot of weight.

Linking to authoritative content and deduplication are really important. To note, @hricky is a leader in the Atomic distro space, so his words here carry a lot of weight.

goroboro added 1 commit

2026-05-12 11:43:14 +00:00

Update for feedback from hricky. We will remove the atomic topic, and rather point to the atomic user's guide wherever relevant 9277aa8519

goroboro commented

2026-05-12 11:49:20 +00:00

I definitely didn't intend anyone to think that I was disregarding what @hricky was suggesting here. I was just trying to ensure that if the quick-docs were providing details on software management, they weren't completely ignoring the fact that this works differently depending on what flavour of Fedora you're using.
I agree that deduplication is important, but the quick-docs do tend to duplicate information anyway. I am just trying to make what currently exists, a bit more accurate, structured, and up to date. If deduplication should be the focus, a lot of this content should just be scrapped.

For what its worth, I have removed the atomic topic entirely, and instead made sure that the dnf topic and the package-management topics point directly to the Atomic Desktop User's Guide. Hopefully that addresses the primary concern here.

Happy to explore other dedup work if that is necessary.

I definitely didn't intend anyone to think that I was disregarding what @hricky was suggesting here. I was just trying to ensure that if the quick-docs were providing details on software management, they weren't completely ignoring the fact that this works differently depending on what flavour of Fedora you're using. I agree that deduplication is important, but the quick-docs do tend to duplicate information anyway. I am just trying to make what currently exists, a bit more accurate, structured, and up to date. If deduplication should be the focus, a lot of this content should just be scrapped. For what its worth, I have removed the atomic topic entirely, and instead made sure that the dnf topic and the package-management topics point directly to the Atomic Desktop User's Guide. Hopefully that addresses the primary concern here. Happy to explore other dedup work if that is necessary.

👍 1

theprogram commented

2026-05-12 13:41:02 +00:00

I think Petr's thumbs up means dedup work is good, and linking to the Atomic info is good.

A big picture assesment of docs and quick docs is certainly going to be useful, lets talk about it in the Matrix channel or at a meeting soon.

I see you had a look at #923

Question to team - who will review and approve this epic commit?

I think Petr's thumbs up means dedup work is good, and linking to the Atomic info is good. A big picture assesment of docs and quick docs is certainly going to be useful, lets talk about it in the Matrix channel or at a meeting soon. I see you had a look at https://forge.fedoraproject.org/docs/quick-docs/issues/923 Question to team - who will review and approve this epic commit?

pbokoc commented

2026-05-12 16:09:10 +00:00

@theprogram wrote in #969 (comment):

I think Petr's thumbs up means dedup work is good, and linking to the Atomic info is good.

A big picture assesment of docs and quick docs is certainly going to be useful, lets talk about it in the Matrix channel or at a meeting soon.

I see you had a look at #923

Question to team - who will review and approve this epic commit?

Yeah, I mean, Quick Docs is a sort of a catch-all for anything that doesn't belong elsewhere. When there's a SIG actively maintaining their docs, like with Atomic, it's better to keep the docs there.

I'll do a review soon.

@theprogram wrote in https://forge.fedoraproject.org/docs/quick-docs/pulls/969#issuecomment-708171: > I think Petr's thumbs up means dedup work is good, and linking to the Atomic info is good. > > A big picture assesment of docs and quick docs is certainly going to be useful, lets talk about it in the Matrix channel or at a meeting soon. > > I see you had a look at #923 > > Question to team - who will review and approve this epic commit? Yeah, I mean, Quick Docs is a sort of a catch-all for anything that doesn't belong elsewhere. When there's a SIG actively maintaining their docs, like with Atomic, it's better to keep the docs there. I'll do a review soon.

goroboro added 1 commit

2026-05-13 09:25:37 +00:00

Pass for style fixes and to address further vale warnings 9d64d39cb8

pbokoc commented

2026-05-26 10:23:56 +00:00

Alright, this has been open for a while and early feedback has been incorporated. I didn't look too deep but I think we can merge this.

Thanks for the PR @goroboro, but let's keep them smaller next time :)

Alright, this has been open for a while and early feedback has been incorporated. I didn't look too deep but I think we can merge this. Thanks for the PR @goroboro, but let's keep them smaller next time :)

👍 1

pbokoc merged commit 6aa69121ca into main

2026-05-26 10:24:13 +00:00

pbokoc referenced this pull request from a commit

2026-05-26 10:24:16 +00:00

Software-Management (#969)

Sign in to join this conversation.

No reviewers