workstation/wg-docs
2
0
Fork 1
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

This repository contains only the WG documentation #506

Merged
tpopela merged 1 commit from tpopela/wg-docs:wg-docs-only into master 2026-05-26 14:58:33 +00:00
Conversation 1 Commits 1 Files changed 11 +2 -227
11 changed files with 2 additions and 227 deletions
Download patch file Download diff file Expand all files Collapse all files

9
README.md
View file

@ -1,8 +1 @@
# Fedora Workstation Working Group
This project is primarily used for Fedora Workstation Working Group issue tracking. It also contains two sets of docs:
1. Fedora Workstation user documentation
2. [Docs about the Fedora Workstation Working Group](https://docs.fedoraproject.org/en-US/workstation-working-group/)
The docs content was originally copied from the [docs template module](https://pagure.io/fedora-docs/template). The [Fedora docs documentation](https://docs.fedoraproject.org/en-US/fedora-docs/contributing-docs/) includes instructions on how to contribute.
This repository contains documentation about the Fedora Workstation Working Group](https://docs.fedoraproject.org/en-US/workstation-working-group/).

5
site.yml
View file

@ -1,14 +1,11 @@
site:
title: Local Preview - Fedora Workstation Documentation
title: Local Preview - Fedora Workstation Working Group Documentation
start_page: workstation-docs::index.adoc
content:
sources:
- url: .
branches: HEAD
start_path: wg-docs
- url: .
branches: HEAD
start_path: user-docs
ui:
bundle:
url: https://asamalik.fedorapeople.org/ui-bundle.zip

22
user-docs/antora.yml
View file

@ -1,22 +0,0 @@
# Name will be mostly visible in the URL. Treat it as an identifier.
# Tip: If you want to use the local preview scripts that come with this
# repository, please change this value in the site.yml file as well. (under
# site/start_page)
name: workstation-docs
# Title will be visible on the page.
title: Fedora Workstation Documentation
# If you don't plan to have multiple versions of the docs (for example, to
# document multiple versions of some software), you can ignore this field.
# Otherwise, change "master" to a specific version.
version: master
# We encourage you to name the index page as "index.adoc". If you absolutely
# have to use a different name, please reflect it here. You can ignore this
# field otherwise.
start_page: ROOT:index.adoc
# This lists all the menu definitions of your component.
nav:
- modules/ROOT/nav.adoc

9
user-docs/modules/ROOT/examples/exampe-example.adoc
View file

@ -1,9 +0,0 @@
This is an example of a example file. Unlike files in `pages/`, files in this directory are not built as standalone pages, but only if they are included in a file within `pages/`. Also unlike examples,
A file in this directory can be included within any file in the `pages/` directory.
Most common use cases for examples is using output from an external script (for example, translation string statistics) in docs. You can use an external script to update the example, and when the site is rebuilt, it will show updated output.
If you want to include this particular example somewhere, you can use the following syntax: `include::example$example-example.adoc[]`.
Note the use of `example$` instead of an actual file location.
See link:https://docs.antora.org/antora/3.0/examples-directory/[Antora docs on examples] for more information about partials.

3
user-docs/modules/ROOT/nav.adoc
View file

@ -1,3 +0,0 @@
* xref:software-repos.adoc[Software Repositories & Tools]
* xref:disk-config.adoc[Disk Configuration]
* xref:problems.adoc[Problem Solving & Issue Reporting]

38
user-docs/modules/ROOT/pages/disk-config.adoc
View file

@ -1,38 +0,0 @@
= Disk Configuration
Fedora Workstation uses a different default disk configuration from other Fedora Editions and Spins. This page describes that configuration along with the motivations behind it.
Other, non-default, disk configuration options are available to be used with Workstation, and can be configured during the disk partitioning step in the installer.
== Btrfs
Btrfs is the default filesystem used by Fedora Workstation. Btrfs has two key advantages for users using the default filesystem configuration:
1. Transparent compression means that data stored on disk uses less space
2. System reinstallation while preserving user data can be supported, while avoiding the issue of volumes running out of space. This is due to the fact that Btrfs subvolumes are not limited to a static predefined size.
Btrfs also provides a range of other features, such as snapshotting and online shrinking, which can be useful for those who want to use them, and can potentially be the basis of future user-facing features.
Fedora Magazine contains a number of https://fedoramagazine.org/?s=btrfs[excellent articles about Btrfs].
== Default Disk Layout
By default, a Workstation installation has the following disk layout:
[cols="1,1,1,1"]
|===
|Role|Filesystem|Mount Point|Size
| EFI System Partition | FAT 32 | `/boot/efi` | 600 MB
| Boot Partition | ext4 | `/boot` | 2.0 GB
| Root Subvolume | Btrfs | `/` |
| Home Subvolume | Btrfs | `/home` |
|===
The first two partitions are common to all Fedora installations, and are required for booting the system. The root subvolume contains the system installation, and the home subvolume contains user data and settings.
== Swap on ZRAM
Fedora Workstation does not use a dedicated swap partition. Instead, it uses zram: an emulated drive that uses RAM for its storage. RAM-based swap is faster than disk-based swap, which avoids the extreme system slowdown and thrashing that can happen with a traditional swap partition.
The zram drive is compressed, to make efficient use of the available memory, and is assigned memory dynamically, meaning that it only uses system RAM when swap is needed.

49
user-docs/modules/ROOT/pages/index.adoc
View file

@ -1,49 +0,0 @@
= Fedora Workstation Documentation
These pages are a general guide to Fedora Workstation. They provide an overview of Workstation, and are intended for Workstation users and Fedora contributors. They should be useful for those who want to know how to use Workstation, as well as those who want to know how it is put together.
== User Help
The content in these pages is technical in nature. If you don't want to know about the technical aspects of Workstation, our https://getfedora.org/en/workstation/[web page] provides an introduction to what you can expect from Fedora Workstation as a user.
Information on how to use the Workstation desktop can be found in the https://help.gnome.org/users/gnome-help/stable/[GNOME user help]. This includes an overview of the desktop, as well as docs on using the apps and system settings.
== Overview
Fedora Workstation is Fedora's official desktop edition. It provides a powerful, easy to use desktop experience. Workstation is intended to be a great general purpose desktop. It also aims to be a fantastic platform for software developers.
Workstation is part of the Fedora project. As such, it shares components, tools, and processes with other Fedora Editions and Spins. However, Workstation is also an independent project, which is able to make its own design and technical decisions, and is a distinct product of its own.
The https://docs.fedoraproject.org/en-US/workstation-working-group/[Workstation Working Group] is the team that has responsibility for Fedora Workstation. However, Workstation wouldn't be possible without the hard work of teams and individuals across the entire Fedora community.
== System Requirements
To have a good experience, hardware with a 40GB SSD disk and 4GB RAM is recommended for Fedora Workstation. However, it is possible to use hardware with lower specifications.
Workstation images are available for x86_64 and aarch64 architectures, providing support for Intel, AMD and ARM processors.
== Getting Workstation
Fedora Workstation comes preinstalled on a number of hardware options. It can also be manually installed using a USB flash drive. The https://fedoraproject.org/workstation/download/[Fedora Workstation download page] provides information on how to do this.
== What's Included
Workstation is built from open source components, many of which are shared with other Fedora Editions and Spins. Key components include the Linux kernel, systemd, DNF, the Wayland display server, the Pipewire multimedia server, NetworkManager, the GNOME Desktop, and the Firefox browser. Each of these components are carefully integrated and tested, to work together as part of a seamless experience.
Workstation also includes a default set of preinstalled applications, to make it easy to get started, and to provide the range of standard utilities that are necessary for a desktop.
In order to prevent Workstation systems from becoming unusable, certain key components are required to be installed, and cannot be removed. These non-removable components include `gnome-shell`, `gnome-control-center`, `grub`, and `NetworkManager`.
== Getting Involved
There are lots of ways to participate in Fedora Workstation. For users, the best places to start include:
* Participating in https://discussion.fedoraproject.org/[Fedora Discussions]
* Chatting in the https://matrix.to/#/#workstation:fedoraproject.org/[#workstation] channel
* Providing support to other users in https://ask.fedoraproject.org/[Ask Fedora]
If you want to help with Fedora Workstation, there are also lots of teams that you can join, including:
* Fedora project teams, including https://docs.fedoraproject.org/en-US/websites/[Websites], https://fedoraproject.org/wiki/Design[Design], https://fedoraproject.org/wiki/QA[QA], https://docs.fedoraproject.org/en-US/package-maintainers/Joining_the_Package_Maintainers/[Packaging] and https://docs.fedoraproject.org/en-US/fedora-docs/[Documentation].
* Upstream projects, particularly the https://www.gnome.org/#community[GNOME Project], which is responsible for much of the Workstation experience.
* The https://docs.fedoraproject.org/en-US/workstation-working-group/[Workstation Working Group], which is open to anyone who wants to be involved in the day to day decisions around Workstation.

31
user-docs/modules/ROOT/pages/problems.adoc
View file

@ -1,31 +0,0 @@
= Problem Solving & Issue Reporting
This page includes general information on how to investigate and report issues with Fedora Workstation.
== Diagnostic Tools
Workstation includes a set of graphical and command line tools which can be used to investigate and diagnose issues, if they happen.
Graphical tools include:
* *System Monitor*: can be used to see if system resources are being exceeded, and which processes are using the most resources.
* *Logs*: a graphical viewer app for system and application logs.
* *Problem Reporting*: automatically detects crashes, and allows reporting of crash data. In some cases the Problem Reporting tool will link to existing issue reports for a crash.
Command line diagnostic tools which are preinstalled in Fedora Workstation include:
* `top`: command line system monitor.
* `journalctl`: command line interface for viewing systemd logs. Learn https://docs.fedoraproject.org/en-US/quick-docs/viewing-logs/[how to get started with journalctl].
* `coredumpctl`: command line interface for analyzing software crashes. https://fedoramagazine.org/file-better-bugs-coredumpctl/[Fedora Magazine has a good article on getting started with coredumpctl].
### Issue Reporting
Issues that need to be tracked as part of the Fedora release process, such as potential release blockers, should be reported against the correct component in https://bugzilla.redhat.com/[Red Hat Bugzilla].
For other issues, it is recommended to create reports directly with the relevant upstream project. The GNOME Project is the upstream for much of the software that makes up Fedora Workstation. Issues with GNOME components can be reported using https://gitlab.gnome.org[GNOME's Gitlab instance].
### Out Of Memory (OOM) Handling
When the system is running out of memory, Fedora Workstation automatically forces processes to quit, in order to ensure that the system can continue to function.
If applications or processes suddenly close, it could be due to memory pressure. Check the logs to see if a OOM event was recorded, and check system resources to see if your system is approaching its memory limits.

47
user-docs/modules/ROOT/pages/software-repos.adoc
View file

@ -1,47 +0,0 @@
= Software Repositories & Tools
This page includes information about the software formats, tools and repositories that are included in Fedora Workstation.
== Default Software Repositories
Workstation comes with a set of software repositories enabled out of the box. These allow preinstalled software to be updated, as well as new packages and apps to be installed.
Workstation's default software repositories are:
* Official Fedora RPM repositories. Workstation system components and applications are provided in RPM format, using the main Fedora repositories.
* Fedora Flatpaks. Workstation comes with the Flatpak app distribution tool installed by default. It also includes a repository of Flatpak apps, which are built and hosted by the Fedora project, and which are available to be installed.
* Linux Vendor Firmware Service (LVFS). Workstation uses fwupd to provide firmware updates from LVFS. This is enabled by default.
== Third-Party Repositories
Fedora Workstation also includes a set of https://docs.fedoraproject.org/en-US/workstation-working-group/third-party-repos/[third-party repositories]. These software repositories are provided by projects and organizations other than Fedora, and provide access to a wider range of software than the default offering. They can be enabled with the click of a button during initial setup, or in the Software app.
== Installing & Updating Software
Workstation includes the GNOME Software app, which makes it easy to find and install apps, and to install software updates.
Workstation also comes with a set of command line tools that can be used for software management. These are:
* `dnf`: Fedora's default package manager. See https://docs.fedoraproject.org/en-US/quick-docs/dnf/[this guide] for information on how to get started with DNF.
* `flatpak`: the Flatpak tool can be used to install and update graphical applications that are provided as Flatpaks. See https://docs.flatpak.org/en/latest/using-flatpak.html[this guide] to get started with the Flatpak CLI.
* `fwupdmgr`: the command line utility for fwupd. This can be used to update firmware.
== Release Schedule, Updates & Upgrades
Fedora Workstation follows the https://docs.fedoraproject.org/en-US/releases/[standard Fedora release schedule]: a new version is produced every six months, and each version receives updates for 13 months.
Fedora's smooth upgrade process means that it's easy to stay up to date, and transitioning from one version to the next is easy and pain free (though we still recommend that you backup before upgrading). Upgrading can be done using the Software app, which shows a notification when a new version is available. You can also https://docs.fedoraproject.org/en-US/quick-docs/dnf-system-upgrade/[upgrade using the command line].
== Proprietary & Patent Encumbered Software
In accordance with Fedora principles and policy, Fedora Workstation only includes open source software. Workstation is also prevented from including patent-encumbered software. This poses challenges in cases where such software is required by particular hardware or multimedia formats.
Open source technologies are always the preferred option for Workstation. However, in important cases where no viable open source option exists, and where it is safe to do so, mechanisms are provided to gain access to particular proprietary and patent encumbered software.
=== NVIDIA Graphics
Fedora Workstation works to ensure that the open source Nouveau driver provides an excellent experience for NVIDIA hardware. However, when features that are exclusive to the proprietary driver are required, it can be installed by enabling the Third Party Repositories.
=== H.264 Codecs
Due to patent issues, Fedora cannot distribute the H.264 multimedia codec itself. However, Workstation does automatically install this codec for users, from a non-Fedora source.

1
user-docs/modules/ROOT/partials/attributes.adoc
View file

@ -1 +0,0 @@
:year: 2021

15
user-docs/modules/ROOT/partials/partial-example.adoc
View file

@ -1,15 +0,0 @@
This is an example of a partial file. Unlike files in `pages/`, files in this directory are not built as standalone pages, but only if they are included in a file within `pages/`. This stops fragments of pages being built and discovered by search engines.
A file in this directory can be included within any file in the `pages/` directory.
Most common use cases for partials are:
. Reusing attributes such as the current year or a release version throughout the entire module while being able to change it easily (such as changing "Fedora 33" to "Fedora 34" when a new release comes out).
. Reusing content such a banner or an infobox (`[NOTE]`, etc.) that appears on multiple pages and needs to have consistent content everywhere (such as a message on some of the quick-docs that warns the reader about their unreviewed status).
In these cases, you can use a partial to include the same content in multiple places, and you only need to change it once to get the change to appear in every spot it's included in. You can see the first example used in `pages/index.adoc` in this repository; note the include statement on top.
If you want to include this particular example somewhere, you can use the following syntax: `include::partial$partial-example.adoc[]`.
Note the use of `partial$` instead of an actual file location.
See link:https://docs.antora.org/antora/3.0/partials-directory/[Antora docs on partials] for more information about partials.