#343 Add docs
Merged 2 years ago by aday. Opened 2 years ago by aday.

Add the docs
Allan Day • 2 years ago  
file added
+3
@@ -0,0 +1,3 @@ 

+ build

+ cache

+ public

file added
+10
@@ -0,0 +1,10 @@ 

+ 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

+ http://creativecommons.org/licenses/by-sa/3.0/. 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.

file modified
+7 -2
@@ -1,3 +1,8 @@ 

- # fedora-workstation

+ # Fedora Workstation Working Group

  

- Fedora Workstation issues 

\ No newline at end of file

+ 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/) includes instructions on how to contribute. 

\ No newline at end of file

file added
+52
@@ -0,0 +1,52 @@ 

+ #!/bin/sh

+ 

+ image="docker.io/antora/antora"

+ cmd="--html-url-extension-style=indexify site.yml"

+ 

+ if uname | grep -iwq darwin; then

+     # Running on macOS.

+     # Let's assume that the user has the Docker CE installed

+     # which doesn't require a root password.

+     echo ""

+     echo "This build script is using Docker container runtime to run the build in an isolated environment."

+     echo ""

+     docker run --rm -it -v "$(pwd):/antora" "${image}" ${cmd}

+ 

+ elif uname | grep -iq linux; then

+     # Running on Linux.

+     # there isn't an antora/aarch64 container, antora can be installed locally

+     # Check whether podman is available, else faill back to docker

+     # which requires root.

+ 

+     if [ -f /usr/local/bin/antora ]; then

+         /usr/local/bin/antora "${cmd}"

+     elif uname -m | grep -iwq aarch64; then

+         echo "no antora/aarch64 container try just \`npm install -g @antora/cli @antora/site-generator-default\`"

+     elif [ -f /usr/bin/podman ]; then

+         echo ""

+         echo "This build script is using Podman to run the build in an isolated environment."

+         echo ""

+         podman run --rm -it -v "$(pwd):/antora:z" "${image}" ${cmd}

+ 

+     elif [ -f /usr/bin/docker ]; then

+         echo ""

+         echo "This build script is using Docker to run the build in an isolated environment."

+         echo ""

+ 

+         if groups | grep -wq "docker"; then

+             docker run --rm -it -v "$(pwd):/antora:z" "${image}" ${cmd}

+         else

+             echo "You might be asked for your password."

+             echo "You can avoid this by adding your user to the 'docker' group,"

+             echo "but be aware of the security implications."

+             echo "See https://docs.docker.com/install/linux/linux-postinstall/"

+             echo ""

+             sudo docker run --rm -it -v "$(pwd):/antora:z" "${image}" ${cmd}

+         fi

+     else

+         echo ""

+         echo "Error: Container runtime haven't been found on your system. Fix it by:"

+         echo "$ sudo dnf install podman"

+         exit 1

+     fi

+ fi

file added
+14
@@ -0,0 +1,14 @@ 

+ server {

+     listen       80;

+     server_name  localhost;

+ 

+     location / {

+         root   /antora/public;

+         index  index.html index.htm;

+     }

+ 

+     error_page   500 502 503 504  /50x.html;

+     location = /50x.html {

+         root   /usr/share/nginx/html;

+     }

+ }

notes/hibernationstatus.md hibernationstatus.md
file renamed
file was moved with no change to the file
file added
+18
@@ -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):/antora:ro" -v "$(pwd)/nginx.conf:/etc/nginx/conf.d/default.conf:ro" -p 8080:80 nginx

+ 

+ elif [ "$(expr substr "$(uname -s)" 1 5)" = "Linux" ]; then

+     # Running on Linux.

+     # Fedora Workstation has python3 installed as a default, so using that

+     echo ""

+     echo "The preview is available at http://localhost:8080"

+     echo ""

+     cd ./public

+     python3 -m http.server 8080

+ fi

file added
+24
@@ -0,0 +1,24 @@ 

+ site:

+   title: Local Preview - Fedora Workstation 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

+     snapshot: true

+   default_layout: with_menu

+ output:

+   clean: true

+   dir: ./public

+   destinations:

+   - provider: archive

+ runtime:

+   fetch: true

+   cache_dir: ./cache

file added
+22
@@ -0,0 +1,22 @@ 

+ # 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

@@ -0,0 +1,9 @@ 

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

@@ -0,0 +1,3 @@ 

+ * xref:software-repos.adoc[Software Repositories & Tools]

+ * xref:disk-config.adoc[Disk Configuration]

+ * xref:problems.adoc[Problem Solving & Issue Reporting]

@@ -0,0 +1,38 @@ 

+ = 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 selected during the disk partitioning step in the installer.

+ 

+ == Btrfs

+ 

+ Btrfs is the default filesystem used by Fedora Workstation. Btrfs has two key advantages for all 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 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"]

+ |===

+ |Role|Filesystem|Mount Point

+ 

+ | EFI System Partition | FAT 32     | `/boot/efi`

+ | Boot Partition       | ext4       | `/boot`

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

\ No newline at end of file

@@ -0,0 +1,49 @@ 

+ = 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 alike. They should be useful for those who want to know how to use Workstation and how it is put together, from a technical perspective.

+ 

+ == 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.

+ 

+ Advice on how to use the Workstation desktop can be found in the built-in *Help* app, which can be launched from the desktop. This user help can also be https://help.gnome.org/users/gnome-help/stable/[browsed online], and includes an overview of the desktop, as well as detailed help 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 decisions, and is a distinct product of its own.

+ 

+ The https://docs.fedoraproject.org/en-US/workstation-working-group/[Workstation Working Group] is the main 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

+ 

+ Hardware with a 40GB SSD disk and 4GB RAM is recommended for Fedora Workstation. It is possible to use hardware with lower specifications. However, the resulting experience may be suboptimal.

+ 

+ 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://getfedora.org/en/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/get-involved/[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. 

\ No newline at end of file

@@ -0,0 +1,31 @@ 

+ = 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.

@@ -0,0 +1,47 @@ 

+ = 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.

+ 

+ === h264 Codecs

+ 

+ Due to patent issues, Fedora cannot directly provide the h264 multimedia codec. However, it is automatically installed for users, from a non-Fedora source. 

\ No newline at end of file

@@ -0,0 +1,1 @@ 

+ :year: 2021

@@ -0,0 +1,15 @@ 

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

file added
+22
@@ -0,0 +1,22 @@ 

+ # 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-working-group

+ 

+ # Title will be visible on the page.

+ title: Fedora Workstation Working Group

+ 

+ # 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

@@ -0,0 +1,9 @@ 

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

@@ -0,0 +1,6 @@ 

+ * xref:what-we-do.adoc[What we do]

+ * xref:governance.adoc[Governance]

+ * xref:members.adoc[Members]

+ * xref:prd.adoc[Workstation PRD]

+ * xref:third-party-repos.adoc[Third-Party Repositories]

+ * xref:schedule.adoc[Release Planning Schedule]

@@ -0,0 +1,28 @@ 

+ = Governance

+ 

+ Governance rules for the Fedora Workstation Working Group, an independent subcommittee of FESCo.

+ 

+ == Membership

+ 

+ Members of the Working Group are chosen by the Working Group as needed to maintain a reasonably-sized working group. The Working Group may fill a seat by selecting a candidate and approving by majority of the Working Group membership. Eligible candidates must be in the FPCA+1 group. The Working Group is encouraged to seek out candidates that have been showing persistent and high-quality contribution to Workstation technology or direction.

+ 

+ xref:members.adoc[See current members list.]

+ 

+ == Meetings

+ 

+ The Working Group meets on a regular basis. A quorum, comprised of a majority of the Working Group, is required to conduct business and make binding decisions at meetings.

+ 

+ The Working Group will keep records of discussions, meetings, and votes, and will make these records public to the Fedora community. The Working Group shall generally be open to public observation. However, the Working Group may meet in private when necessary to discuss for sensitive issues, such as legal issues, provided that such private meetings are rare and that the public record indicates that a private meeting occurred and the general topic of the private discussion.

+ 

+ == Making decisions

+ 

+ The Working Group may make binding decisions on any matters affecting the Fedora Workstation product, including any software contained in the product.

+ 

+ The Working Group generally operates by consensus. Formal votes are not required to resolve issues except when disagreement exists. When Working Group members wish to hold a vote, voting may occur either using an online platform accessible to the Fedora community, or during meetings of the Working Group. Working group members can vote +1 to approve, -1 to disagree, or 0 to abstain; a majority vote is necessary for a measure to pass, with abstain votes not being included in the count.

+ 

+ Working Group decisions may be overruled by FESCo.

+ 

+ == Changing these rules

+ 

+ This document was originally approved by consensus of the initial Working Group members and by FESCo. Future substantive changes may be approved by majority vote and sent to FESCo for acceptance.

+ 

@@ -0,0 +1,43 @@ 

+ = Fedora Workstation Working Group

+ 

+ https://getfedora.org/en/workstation/[Fedora Workstation] is Fedora's official desktop edition. It aims to be a compelling desktop OS which is appropriate for a wide range of users, especially for software developers. Workstation is built on a technology base that is shared with the other official Fedora editions, and is the product of work that happens across the Fedora project. It is also a project in its own right and can make independent technical decisions.

+ 

+ The Workstation Working Group is the team which is responsible for Fedora Workstation. It is comprised of xref:members.adoc[official members] who have decision making powers, as well as other contributors. The working group is subordinate to https://docs.fedoraproject.org/en-US/fesco/[FESCo].

+ 

+ == Mission

+ 

+ The Workstation Working Group strives to make Fedora Workstation a compelling and competitive desktop OS, particularly for developers. Where possible, it aims to have a guidance and steering role, though it does also hold ultimate responsibility for Workstation technical decisions.

+ 

+ The working group's main roles include:

+ 

+ * Tracking and coordinating technical and UX changes

+ * Final decision making on Workstation technical decisions

+ * Ensuring quality in the Workstation product

+ * Setting and steering technical direction

+ * Workstation promotion and evangelism

+ * Coordinating Workstation activities with the rest of the Fedora project

+ * Developing the Workstation contributor community

+ 

+ See xref:what-we-do.adoc[what we do] for a more detailed list of activities.

+ 

+ == Getting in touch, contributing

+ 

+ * Chat: \#fedora-workstation on https://libera.chat/[irc.libera.chat] / https://matrix.to/#/#workstation:fedoraproject.org/[#workstation on Matrix]

+ * Mailing list: https://lists.fedoraproject.org/admin/lists/desktop.lists.fedoraproject.org/[desktop@lists.fedoraproject.org] (https://lists.fedoraproject.org/archives/list/desktop@lists.fedoraproject.org/[see archives])

+ * Issue tracking: https://pagure.io/fedora-workstation/issues[pagure.io/fedora-workstation/]

+ 

+ == Meetings

+ 

+ Meetings are open to all current and potential workstation contributors.

+ 

+ * Day & time: https://calendar.fedoraproject.org/workstation/[Tuesdays, 10:00 US Eastern]

+ * Location: https://bluejeans.com/395383051[bluejeans.com/395383051]

+ 

+ See the mailing list for more details, including agendas and minutes.

+ 

+ == Policies and resources

+ 

+ * xref:governance.adoc[Workstation Working Group governance]

+ * https://docs.fedoraproject.org/en-US/fesco/Third_Party_Repository_Policy/[FESCo third-party repository policy]: how the workstation third-party repositories are required to work

+ * xref:third-party-repos.adoc[Workstation third-party repositories]: information for users

+ * https://fedoraproject.org/wiki/Workstation[Workstation WG wiki pages (retired)]: historical workstation material

@@ -0,0 +1,20 @@ 

+ = Members

+ 

+ The current members of the Workstation Working Group are:

+ 

+ * Michael Catanzaro (mcatanzaro)

+ * Matthias Clasen (mclasen)

+ * Allan Day (aday)

+ * Neal Gompa (King_InuYasha, Son_Goku)

+ * Chris Murphy (chrismurphy)

+ * Jens Petersen (petersen)

+ * Tomáš Popela (tpopela)

+ * Kalev Lember (kalev)

+ * Owen Taylor (otaylor)

+ 

+ Previous members include:

+ 

+ * Langdon White (langdon)

+ 

+ See xref:governance.adoc[governance] to see how official members are appointed.

+ 

@@ -0,0 +1,194 @@ 

+ = Fedora Workstation PRD

+ 

+ *May 2022*

+ 

+ This document provides an overview of the goals and objectives of Fedora Workstation. It is intended to allow people to understand the role of Fedora Workstation and how it is likely to develop in future.

+ 

+ The Fedora Workstation PRD is primarily intended for other Fedora Project teams, contributors and stakeholders, so they can better understand Workstation’s role, goals and current priorities.

+ 

+ == Fedora Workstation Vision

+ 

+ Fedora Workstation envisions an open world where developers and creators can easily make new and exciting things with accessible digital platforms.

+ 

+ == Fedora Workstation Mission

+ 

+ Our mission is to continuously advance Fedora Workstation: to make it an ever more capable and powerful operating system for laptops and desktops, and to continually narrow the gap between it and the needs of its users. We aim to continually increase Workstation's capacity to help developers and creators, and to grow the Workstation user and contributor community.

+ 

+ == The Workstation Market

+ 

+ This section describes the audience for Fedora Workstation, our main pitch for that audience, and our main routes to market.

+ 

+ === Market opportunity

+ 

+ Laptop and desktop devices are at the heart of many creative areas, including software, multimedia, engineering, science, and design. In all these fields, a desktop computer is an essential tool. As such, the critical role of the desktop is firmly established in the market.

+ 

+ The desktop market also has important effects which are felt more widely. Desktops can help to popularize the technologies and ecosystems with which they are associated, and they can be a vehicle for communicating values, principles and practices.

+ 

+ Finally, desktop computers are an important gateway for people who are starting out in their personal journeys in computing, and are a powerful educational and learning tool. Many people remember the first time they installed a Linux operating system as a key moment in their lives. Fedora Workstation wants to be part of that experience, and to make it as good as it possibly can be.

+ 

+ ==== A desktop for developers and creators

+ 

+ Workstation's historical focus has been on developer use cases. In practical terms, this translates to:

+ 

+ * Availability of high quality developer tools, frameworks and platforms.

+ * Fantastic command line experience.

+ * Prioritization of desktop features which are particularly relevant to developers, including multi-monitor, VPN, and remote desktop.

+ * A desktop experience which caters to developers, with features like keyboard-based app launching, window snapping, and a focus on distraction free computing.

+ * Support for developer class hardware.

+ * A high level of reliability and stability.

+ 

+ However, it should be stressed that developers also require other more basic desktop features and product qualities. Our focus on developers therefore does not compromise our goal to create a polished and user friendly system that appeals to a wide general audience. Many changes and improvements we implement for developers are equally beneficial to other user segments.

+ 

+ Most recently, we have expanded our goals to include other types of digital content creation, in addition to software developers. This expansion of the link:https://fedoraproject.org/wiki/Workstation/Workstation_PRD[initial Fedora Workstation goals] reflects our success in the developer space, and a desire to have broader aspirations.)

+ 

+ ==== Use cases

+ 

+ Broad user types that we are interested in include:

+ 

+ * Undergraduate and postgraduate students

+ * Independent developers and content creators

+ * Developers working in both large and small organizations

+ 

+ Activities that we are focused on supporting include:

+ 

+ * Student coursework for CS programs

+ * Full stack software development

+ * Game development — and playing games!

+ * DevOps and systems administration

+ * Podcasting and video streaming

+ 

+ === Why use Fedora Workstation

+ 

+ First and foremost, Fedora Workstation fulfills the most important, basic requirements that people have for a modern desktop operating system:

+ 

+ * can be relied upon to be usable whenever you need it, without bugs or software updates getting in your way

+ * a large collection of applications and other software available to install

+ * easy to use and learn, from the very first use or install, through to learning more advanced tasks

+ * support for a wide range of high-quality hardware

+ * fantastic user experience

+ 

+ Additionally, it has special qualities which are unique to Fedora:

+ 

+ * provides access to the latest and best open source software, including new cutting-edge features and technologies

+ * a welcoming and supportive user community

+ * part of the wider Fedora and Red Hat ecosystem

+ * developed in the open, in collaboration with upstream projects and communities, following the open source way

+ 

+ === Go to market

+ 

+ Since our goal is to increase the number of people using Fedora Workstation, it is critical to ensure direct and effective routes to our target audiences. There are three primary routes to market.

+ 

+ ==== 1. Self-installation

+ 

+ Self-installation has been and continues to be our primary route to market. Here, the user installs and manages the system themselves.

+ 

+ Some requirements here:

+ 

+ * Attractive landing site and download page

+ * Create install media from a variety of operating systems (via Fedora Media Writer)

+ * Live media for testing and demos

+ * Install alongside a pre existing OS (primarily Windows)

+ * Easy access to help when questions arise

+ 

+ ==== 2. Preinstalled OS

+ 

+ Here, the operating system is installed by the hardware manufacturer prior to it being shipped to the user. The preinstallation route to market has been a significant focus for Workstation, that has delivered results through our partnership with Lenovo. 

+ 

+ Requirements for manufacturer preinstallation include:

+ 

+ * Supporting the hardware that Fedora is preinstalled on (to be delivered in partnership with key hardware vendors)

+ * Initial system setup should be compatible with OEM installation scenarios

+ * Firmware updates for hardware shipped with Fedora

+ 

+ ==== 3. Managed deployments

+ 

+ In a managed deployment, the route to market is through organizations which choose to widely deploy and support Fedora. The OS is installed by an administrator, and aspects of the machine are monitored and administered by the organization.

+ 

+ Managed deployments are less developed than Workstation’s other routes to market and this route poses some challenges. However, it remains an important area that we continue to investigate.

+ 

+ Relevant features include:

+ 

+ * Initial system setup

+ * Enterprise login

+ * Remote auditing

+ * Remote configuration and management

+ * System customization for managed cases (for example, customized initial setup and Software categories)

+ 

+ == Fedora Workstation Objectives

+ 

+ This objectives section covers our operational activities in more detail, in pursuit of the broader ambitions described above.

+ 

+ In operational terms, Fedora Workstation’s main goals are to:

+ 

+ * Be a great developer workstation

+ * Be a great general-purpose OS targeting laptops and desktops

+ * Work well for content creation (podcasts, video streaming, etc)

+ 

+ Fedora Workstation has had a period of success and has been recognised for delivering a high-quality desktop with new and exciting features. As we move forward, we aim to continue on this upward trajectory by continuing to ensure quality and reliability, while pursuing technology and UX improvements.

+ 

+ Particular areas of interest include:

+ 

+ * Developer focused features

+ * Growing the Fedora contributor community

+ * Features and capabilities for content creation, such as podcasting and video streaming

+ * Supporting managed Fedora Workstation deployments

+ * Filling in outstanding missing pieces around hardware support, multimedia support, security features

+ * Increasing the number of apps that are available to install out of the box

+ * Enhanced marketing and mindshare

+ 

+ === Functional requirements

+ 

+ The following describes the features and product attributes that we believe are most important to Fedora Workstation’s success.

+ 

+ ==== Quality releases

+ 

+ We continually work to ensure that the core product offered is of the highest quality possible. This includes keeping the core test matrix as small as possible, using a high degree of testing automation, and collaborating with upstream projects to increase general test coverage of core modules. We work closely with Fedora QE and Release Engineering to ensure that Workstation releases are of consistently high quality.

+ 

+ ==== Robust upgrades

+ 

+ Because of the fast refreshes and relatively short life cycle of Fedora Linux releases, we need upgrades to be pain-free. Users should approach them without fear.

+ 

+ Upgrading the system multiple times through the upgrade process should give a result that is the same as an original install of Fedora Workstation. Upgrade should be a safe process that never leaves the system needing manual intervention.

+ 

+ If there are any problems with an upgrade or an upgrade breaks a configuration script, we want to offer an easy way for users to roll back such upgrades and changes.

+ 

+ ==== Broad application availability

+ 

+ Our goal is to provide easy access to common best in class desktop applications, including:

+ 

+ * general desktop apps for web browsing, music, cloud drives and chat

+ * development tools, including IDEs, compilers, debugging and testing tools

+ * content creation tools, such as multimedia recording and process, and image and video editing

+ 

+ Flatpak and the third party repositories are key initiatives towards this goal. We also aim to extend the availability of apps in the main Fedora repositories wherever possible.

+ 

+ ==== Platform integration

+ 

+ Software installed by default in Fedora Workstation should integrate with other platform components and adhere to the overall vision for Fedora Workstation. Software is expected to support Wayland and follow the GNOME Human Interface Guidelines. Exceptions to this should be rare.

+ 

+ ==== Accessibility

+ 

+ From installing to using the Fedora Workstation, users with special needs shouldn’t be presented with any obstacles and have a pleasant experience.

+ 

+ ==== Virtual machine and container experience

+ 

+ We aim to provide a first class experience for containers and virtual machines, including:

+ 

+ * Availability of container tools, including Podman, Skopeo, Buildah and OpenShift.

+ * High quality, easy to use, virtual machine tooling, through GNOME Boxes.

+ * High quality container development experience, including desktop integration for containers, and availability of OpenShift tooling and integrations (for example, the OpenShift VS Code plugin).

+ 

+ ==== Encapsulation of development environments (Toolbx)

+ 

+ It should be possible to target deployment environments that are different from the operating system itself. An upgrade to a newer version of Fedora Workstation should not mean that a coding project needs to be modified to work with new versions of libraries and runtimes.

+ 

+ ==== Support multimedia use cases

+ 

+ * Available applications to record and stream audio and video

+ * Support for AV equipment

+ * OS support for high dynamic range (primarily of interest to those doing image and video editing)

+ * Hardware acceleration for video encoding

+ 

+ ==== Documentation

+ 

+ Users and administrators should be able to find information about how to use and manage their operating system on the system itself (offline through GNOME Help, manual pages and others) as well as on Fedora Project websites.

@@ -0,0 +1,54 @@ 

+ = Release Planning Schedule

+ 

+ The following is the template for the Workstation Working Group's release schedule. It follows the main Fedora release schedule, with additional check-in steps.

+ 

+ The schedule is meant to evolve as we use it, so please update this page as necessary.

+ 

+ [cols="1,3,5"]

+ |===

+ |Week |Milestone| Tasks

+ 

+ |1

+ |Fedora development cycle begins

+ |

+ 

+ |20

+ |System-wide change proposal deadline

+ |

+ 

+ |21

+ |Self-contained change proposal deadline

+ |

+ 

+ |26

+ |GNOME beta target date & UI freeze

+ |1. check that all GNOME modules have releases, 2. update packages with the GNOME beta, 3. notify QA when the GNOME beta is available in Fedora, 4. plan a test week for when the beta will be available

+ 

+ |27

+ |Fedora branches from rawhide

+ |

+ 

+ |28

+ |GNOME test week happens around now

+ |

+ 

+ |30

+ |GNOME RC target date

+ |

+ 

+ |32

+ |Fedora beta release

+ |

+ 

+ |33

+ |GNOME stable target date

+ |1. update packages with the new GNOME release, 2. notify QA when the update is complete, 3. start preparing GNOME Fedora Flatpak updates

+ 

+ |35

+ |Fedora final freeze

+ |Start distributing GNOME Fedora Flatpak updates (should happen 2 weeks prior to expected release date)

+ 

+ |37

+ |Fedora stable release early target date

+ |Workstation publicity to be released with the new stable release: blog post, website updates, talks, etc

+ |=== 

@@ -0,0 +1,118 @@ 

+ = Third-Party Repositories

+ 

+ ////

+ Do not remove this page! It is linked to from apps in Fedora Workstation, including Software.

+ 

+ Goals for this page:

+ 

+ * describe what the 3rd party repos are

+ * explain how the 3rd party repos can be used

+ * list which repos and software are included

+ * assert Fedora's commitment to free and open source software, and list free/open alternatives

+ ////

+ 

+ The Fedora Workstation Third Party repositories provide access to additional desktop software that is not included in Fedora's own repos. The repositories are selected and managed by the xref:index.adoc[Fedora Workstation Working Group], in accordance with https://docs.fedoraproject.org/en-US/fesco/Third_Party_Repository_Policy/[FESCo's third party repository policy].

+ 

+ The third-party repositories exist to provide access to additional software that may be necessary or important for users to have access to. This includes some proprietary software.

+ 

+ While facilitating the use of a small selected set of proprietary software, the Fedora project continues to strongly believe in and promote https://www.gnu.org/philosophy/free-sw.en.html[free and open source software]. As a result, third party repositories must be enabled by the user in order to be used, and open source alternatives are suggested below.

+ 

+ == How to use

+ 

+ The following are basic instructions for how to use the third-party repositories.

+ 

+ === Enabling third-party repositories

+ 

+ To install software from the third-party repositories, they must first be enabled. The easiest way to do this is in the Third-Party Repositories page of initial setup.

+ 

+ Alternative methods to enable the third-party repositories include:

+ 

+ * Through the info bar that is shown in the Software app when third-party repositories are not enabled.

+ * Enabling Third-Party Repositories in the Software app's Software Repository settings.

+ 

+ === Installing from third-party repositories

+ 

+ Once the repos are enabled, the software they contain can be installed in the usual way. The repos can also be searched and installed using the dnf or flatpak commands, depending on the packaging format used.

+ 

+ === Managing third-party repositories

+ 

+ The Software Repository settings in the Software app can be used to see which third-party repositories are enabled, or to enable and disable individual repositories.

+ 

+ == Included software

+ 

+ The following software is included in the third-party repositories:

+ 

+ [cols="1,1,1,1,1,1"]

+ |===

+ |Name|Description|Repository name|Available since|Open source?|Open source alternatives

+ 

+ |Bitwarden

+ |Password manager

+ |``flathub``

+ |F35

+ |Yes

+ |N/A

+ 

+ |Discord

+ |Messaging, voice and video calls

+ |``flathub``

+ |F35

+ |No

+ |Matrix, Jitsi, others

+ 

+ |Google Chrome

+ |Web Browser

+ |``google-chrome``

+ |F25

+ |No

+ |Chromium, Firefox, Web

+ 

+ |Microsoft Teams

+ |Group chat and calls

+ |``flathub``

+ |F35

+ |No

+ |Matrix, Jitsi, others

+ 

+ |Minecraft

+ |Game

+ |``flathub``

+ |F35

+ |No

+ |None

+ 

+ |NVIDIA Graphics Driver

+ |Driver for NVIDIA graphics cards

+ |``rpmfusion-nonfree-nvidia-driver``

+ |F28

+ |No

+ |https://nouveau.freedesktop.org/[Nouveau: Accelerated Open Source driver for nVidia cards] (preinstalled in Fedora)

+ 

+ |Postman

+ |Developer tool for building and using APIs

+ |``flathub``

+ |F35

+ |No

+ |Insomnia Rest Client

+ 

+ |PyCharm

+ |Python IDE

+ |``phracek-PyCharm``

+ |F23

+ |Yes

+ |N/A

+ 

+ |Skype

+ |Messaging, voice and video calls

+ |``flathub``

+ |F35

+ |No

+ |Matrix, Jitsi, others

+ 

+ |Steam

+ |Gaming platform

+ |``rpmfusion-nonfree-steam``

+ |F28

+ |No

+ |None

+ |===

@@ -0,0 +1,17 @@ 

+ = What we do

+ 

+ Some of the things we do in pursuit of these goals are:

+ 

+ * Design and development work to integrate upstream components

+ * Testing upcoming releases and features

+ * Seeking out and engaging contributors from outside the group

+ * Coordinating and organising testing initiatives

+ * Tracking and resolving workstation issues

+ * Deciding which packages are to be included, including which apps are pre-installed

+ * Making the final call on major technical changes

+ * Ensuring that Fedora processes are adhered to for Workstation, including change and release processes

+ * Maintaining the Workstation web pages

+ * Facilitating technical discussions

+ * Reviewing and critiquing technical plans

+ * Publicising the changes in each Workstation release

+ * Communicating Workstation changes to other Fedora teams

@@ -0,0 +1,1 @@ 

+ :year: 2021

@@ -0,0 +1,15 @@ 

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

This adds the existing docs from https://pagure.io/fedora-workstation/workstation-docs/ , plus an additional new set of workstation user docs.

If we merge this, then the workstation-docs repo will need to be retired.

Thanks @chrismurphy . The WG was happy for me to proceed with this, so I'll merge.

Pull-Request has been merged by aday

2 years ago