docs: Update README verbiage & add translation info

2026-08-25 14:53:21 +00:00 · 2025-09-26 09:30:35 -06:00
35 changed files with 72 additions and 218 deletions
@@ -1,8 +0,0 @@
- [ ] I have disclosed use of any AI generated code in my commit messages.
-  - If you are using an LLM, and do not fully understand the changes it is making to the code base, do not create a PR.
-  - In our experience, AI generated code often results in overly complex code that lacks enough context for a proper fix or feature inclusion. This results in considerably longer code reviews. Due to this, AI authored or partially authored PRs may be closed without comment.
- [ ] I understand these changes in full and will be able to respond to review comments.
- [ ] My change is accurately described in the commit message.
- [ ] My contribution is tested and working as described.
- [ ] I have read the [Developer Certificate of Origin](https://developercertificate.org/) and certify my contribution under its conditions.
-
@@ -17,12 +17,13 @@ jobs:
  Test:
    runs-on: ubuntu-latest
    container:
-      image: archlinux:base-devel
+      image: archlinux:latest
      volumes:
        - /:/host
    steps:
    - run: >
-        pacman --noconfirm --needed -Syu
+        pacman --noconfirm -Syu
+        base-devel
        cargo
        clang
        desktop-file-utils
@@ -30,7 +31,6 @@ jobs:
        gtk3
        gtk4
        just
-        libdisplay-info
        libinput
        libxkbcommon
        llvm
@@ -47,7 +47,7 @@ jobs:
        flatpak
        nasm
    - run: rm -rf /host/usr/local/lib/android # Free space
-    - uses: actions/checkout@v6
+    - uses: actions/checkout@v3
      with:
        submodules: recursive
    # Safe directory behavior seems to have issues with `container:`
@@ -106,7 +106,3 @@
 	path = pop-launcher
 	url = https://github.com/pop-os/launcher.git
 	branch = master
-[submodule "cosmic-monitor"]
-	path = cosmic-monitor
-	url = https://github.com/pop-os/cosmic-monitor.git
-	branch = master
@@ -1,6 +1,6 @@
 # COSMIC Desktop

-[COSMIC](https://system76.com/cosmic) is a desktop environment offering performance, efficiency, and personalization to empower a wide variety of use cases.
+Currently in **beta** for Epoch 1 (the first release), which is nearly feature-complete and in the final bug fixing stage. Testing instructions for various distributions are below.

 ## Components of COSMIC Desktop
 * [cosmic-applets](https://github.com/pop-os/cosmic-applets)
@@ -14,7 +14,6 @@
 * [cosmic-idle](https://github.com/pop-os/cosmic-idle)
 * [cosmic-initial-setup](https://github.com/pop-os/cosmic-initial-setup)
 * [cosmic-launcher](https://github.com/pop-os/cosmic-launcher)
-* [cosmic-monitor](https://github.com/pop-os/cosmic-monitor)
 * [cosmic-notifications](https://github.com/pop-os/cosmic-notifications)
 * [cosmic-osd](https://github.com/pop-os/cosmic-osd)
 * [cosmic-panel](https://github.com/pop-os/cosmic-panel)
@@ -44,15 +43,17 @@

 ## Installing on Pop!\_OS

-### Pop!\_OS 24.04
+COSMIC DE is in its first beta release. We're in a bug fixing stage of development with features largely complete for the first release. Using and testing the beta is welcome. 

-COSMIC DE's first release (Epoch 1) is included in Pop!\_OS 24.04. There are two ways to get the 24.04 release:
+### Pop!\_OS 24.04 Beta

- Install it from the [latest release ISO](https://system76.com/cosmic/).
+The recommended way to test COSMIC Epoch on Pop!\_OS is by using the Pop!\_OS 24.04 LTS Beta release. There are two ways to get the 24.04 Beta:
+
+- Install it from the [latest Beta release ISO](https://system76.com/cosmic/).
 - Upgrade an existing Pop!\_OS 22.04 installation using the following command: `pop-upgrade release upgrade -f`
    - If you experience problems during the upgrade, please open an issue in the [pop-upgrade GitHub repository](https://github.com/pop-os/upgrade) or join the [Pop!\_OS Mattermost chat server](https://chat.pop-os.org) for assistance.

-COSMIC users, including Pop!_OS users, are welcome to join the [Pop!\_OS Mattermost chat server](https://chat.pop-os.org) to receive news about development. Join the [COSMIC Epoch channel](https://chat.pop-os.org/pop-os/channels/cosmic-epoch) for COSMIC user discussion, or the [Development channel](https://chat.pop-os.org/pop-os/channels/development) for developer-oriented discussion.
+Pop!\_OS 24.04 Beta installations will be upgradable to the final 24.04 release, but some manual interventions may occasionally be required during development. If you're using Pop!\_OS 24.04 Beta, then it's recommended to join the [Pop!\_OS Mattermost chat server](https://chat.pop-os.org) to receive news about the 24.04 development cycle. Join the COSMIC Epoch channel.

 ### Pop!\_OS 22.04

@@ -117,39 +118,31 @@ Then log out, click on your user, and a sprocket at the bottom right shows an ad
 For a more detailed discussion, consider the [relevant section in the Arch wiki](https://wiki.archlinux.org/title/COSMIC).

 ## Installing on Fedora Linux
-
-COSMIC can be installed from the built-in repositories on Fedora 41+:
-
+Cosmic may be installed via a Fedora COPR repository.
 ```
-sudo dnf install @cosmic-desktop-environment
+dnf copr enable ryanabx/cosmic-epoch
+dnf install cosmic-desktop
 ```

-Alternatively, for more up-to-date COSMIC packages (but less quality control), you can use the nightly COPR builds:
-
-```
-sudo dnf copr enable ryanabx/cosmic-epoch && sudo dnf install cosmic-desktop
-```
-
-After installing, log out, click on your user, and use the sprocket in the bottom right to select the COSMIC desktop environment before logging in.
-For more information, check the [Fedora Wiki COSMIC SIG page](https://fedoraproject.org/wiki/SIGs/COSMIC) or the [COPR page](https://copr.fedorainfracloud.org/coprs/ryanabx/cosmic-epoch/).
+Then log out, click on your user, and a sprocket at the bottom right shows an additional entry alongside your desktop environments. Change to COSMIC and proceed with log in.
+For further information, you may check the [COPR page](https://copr.fedorainfracloud.org/coprs/ryanabx/cosmic-epoch/).

 ## Installing on NixOS
 The COSMIC module on NixOS can be enabled by adding the following lines to
 your NixOS configuration file (`configuration.nix` or in your Flake):
 ```nix
-{
-  # Enable the COSMIC login manager
+  # Enable the login manager
  services.displayManager.cosmic-greeter.enable = true;
-
-  # Enable the COSMIC desktop environment
+  # Enable the COSMIC DE itself
  services.desktopManager.cosmic.enable = true;
-}
+  # Enable XWayland support in COSMIC
+  services.desktopManager.cosmic.xwayland.enable = true;
 ```

 While some packages like `cosmic-session` might be present in prior versions,
 the modules that add full support for COSMIC were added in **NixOS 25.05**.

-You can find more details on the [NixOS Wiki](https://wiki.nixos.org/wiki/COSMIC).
+You can find more details in the [NixOS 25.05 release notes](https://nixos.org/manual/nixos/unstable/release-notes#sec-release-25.05).


 ## Installing on openSUSE tumbleweed
@@ -165,31 +158,22 @@ For further information, you may check the [OBS page](https://build.opensuse.org
 ## Installing on Gentoo Linux
 COSMIC can be installed on Gentoo via a custom overlay. Add the overlay using your preferred overlay manager (such as eselect), and then install the desktop environment:

-`eselect repository add	cosmic-overlay git https://github.com/fsvm88/cosmic-overlay.git`
+`eselect repository add cosmic-overlay git https://github.com/fsvm88/cosmic-overlay.git`

-Next, synchronize the repository with
-`emaint sync -r cosmic-overlay`
+Next, install the COSMIC desktop environment and its associated themes:

-and install the COSMIC desktop environment and its associated themes:
+`emerge cosmic-meta pop-theme-meta`

-`emerge cosmic-meta pop-theme-meta -av`
-
-Please note that the ebuilds have testing keywords and need to unmasked on stable systems for successful installation.
-
-Then log out, and switch the desktop environment to COSMIC, the procedure depends on your login manager.
+Then log out, click on your user, and a sprocket at the bottom right shows an additional entry alongside your desktop environments. Change to COSMIC and proceed with log in.
 For further information, you may check the [Gentoo Wiki](https://wiki.gentoo.org/wiki/COSMIC) or [Overlay Repository](https://github.com/fsvm88/cosmic-overlay).

 ## Setup on distributions without packaging of COSMIC components

-The COSMIC desktop environment requires a few dependencies. The rustc and just packages of your distro may be too old, so we recommend installing rustc and cargo with rustup, and installing just with cargo.
+The COSMIC desktop environment requires a few dependencies:
 (This list does not try to be exhaustive, but rather tries to provide a decent starting point. For detailed instructions, check out the individual projects):

 - [just](https://github.com/casey/just)
 - rustc
- cargo
- c compiler (cc)
- make
- git
 - libwayland
 - mesa (or third-party libEGL/libGL implementations, though interfacing with mesa's libglvnd is generally recommended).
 - libseat
@@ -197,17 +181,16 @@ The COSMIC desktop environment requires a few dependencies. The rustc and just p
 - libinput
 - udev
 - dbus
- libdisplay-info-dev
- libgstreamer1.0-dev
- libgstreamer-plugins-base1.0-dev

 optionally (though the build-system might currently require these libraries):
 - libsystem
 - libpulse
+- pop-launcher
 - libexpat1
 - libfontconfig
 - libfreetype
 - lld
+- cargo
 - libgbm-dev
 - libclang-dev
 - libpipewire-0.3-dev
@@ -216,79 +199,17 @@ Note: `libfontconfig`, `libfreetype`, and `lld` are packages specific to Linux d

 The required ones can be installed with:
 ```
-sudo apt install -y \
-  build-essential \
-  dbus \
-  git \
-  libdbus-1-dev \
-  libdisplay-info-dev \
-  libflatpak-dev \
-  libglvnd-dev \
-  libgstreamer-plugins-base1.0-dev \
-  libgstreamer1.0-dev \
-  libinput-dev \
-  libpam0g-dev \
-  libpixman-1-dev \
-  libseat-dev \
-  libssl-dev \
-  libwayland-dev \
-  libxkbcommon-dev \
-  rustup \
-  udev
-
-rustup toolchain install stable
-cargo install just
+sudo apt install just rustc libglvnd-dev libwayland-dev libseat-dev libxkbcommon-dev libinput-dev udev dbus libdbus-1-dev libpam0g-dev libpixman-1-dev libssl-dev libflatpak-dev -y
 ```

 and the optional ones with:
 ```
-sudo apt install -y \
-  libclang-dev \
-  libexpat1-dev \
-  libfontconfig-dev \
-  libfreetype-dev \
-  libgbm-dev \
-  libpipewire-0.3-dev \
-  libpulse-dev \
-  libsystemd-dev \
-  lld \
-  mold
+sudo apt install libsystemd-dev libpulse-dev pop-launcher libexpat1-dev libfontconfig-dev libfreetype-dev mold cargo libgbm-dev libclang-dev libpipewire-0.3-dev -y
 ```

 They can be installed all at once with:
 ```
-sudo apt install -y \
-  build-essential \
-  dbus \
-  git \
-  libclang-dev \
-  libdbus-1-dev \
-  libdisplay-info-dev \
-  libexpat1-dev \
-  libflatpak-dev \
-  libfontconfig-dev \
-  libfreetype-dev \
-  libgbm-dev \
-  libglvnd-dev \
-  libgstreamer-plugins-base1.0-dev \
-  libgstreamer1.0-dev \
-  libinput-dev \
-  libpam0g-dev \
-  libpipewire-0.3-dev \
-  libpixman-1-dev \
-  libpulse-dev \
-  libseat-dev \
-  libssl-dev \
-  libsystemd-dev \
-  libwayland-dev \
-  libxkbcommon-dev \
-  lld \
-  mold \
-  rustup \
-  udev
-
-rustup toolchain install stable
-cargo install just
+sudo apt install just rustc libglvnd-dev libwayland-dev libseat-dev libxkbcommon-dev libinput-dev udev dbus libdbus-1-dev libsystemd-dev libpixman-1-dev libssl-dev libflatpak-dev libpulse-dev pop-launcher libexpat1-dev libfontconfig-dev libfreetype-dev mold cargo libgbm-dev libclang-dev libpipewire-0.3-dev libpam0g-dev -y
 ```

 ### Testing
@@ -328,12 +249,9 @@ These and the `justfile` inside this repository may be used as references on how

 ### Versioning

-COSMIC DE is a work in progress with many moving pieces.
+COSMIC DE is still a work-in-progress and thus does not follow a versioning scheme yet.
 We do our best to keep the referenced submodule commits in this repository building and working together; as a consequence, they might not contain the latest updates and features from these repositories (yet).
-
-The commits corresponding with the current release are tagged `epoch-X.Y.Z`, where `X` is the major release and the last two numbers denote incremental minor releases. (During development of new major versions, an additional `-alpha.Y.Z` or `-beta.Y.Z` may be appended.)
-
-COSMIC Epoch version numbers are mainly for the benefit of non-Pop!_OS distributions; Pop!_OS uses its own build system, and typically receives updates to individual submodules before they're tagged as part of a COSMIC Epoch release.
+The commits corresponding with the current beta release are tagged `epoch-1.0.0-beta.X.Y`, where `X` is the beta release and `Y` is the minor release.

 ## Translating

@@ -34,8 +34,8 @@ https://gitlab.freedesktop.org/wlroots/wlroots/-/wikis/DRM-Debugging documents h

 ## Frozen desktop

-If the desktop is frozen and `ctrl+alt+f*` don't work to change to a TTY, [the magic SysRq key](https://www.kernel.org/doc/html/latest/admin-guide/sysrq.html) with `r` can be used to switch input into raw mode, so the kernel will handle the tty switch key binding. `/etc/sysctl.conf` or `/etc/sysctl.d` may need to be edited first to set `kernel.sysrq=1` or another value that allows this command.
+If the desktop is frozen and `ctrl+alt+f*` don't work to change to a TTY, [the magic SysRq key](https://www.kernel.org/doc/html/latest/admin-guide/sysrq.html) with `r` can be used to swich input in raw mode, so the kernel will handle the tty switch key binding. /etc/sysctl.conf` or `/etc/sysctl.d` may need to be edited first to set `kernel.sysrq=1` or another value that allows this command.

 It is also possible to connect over `ssh` from another computer.

-Then `pidof cosmic-comp` can be used to get the PID of the compositor. Then it is possible to investigate further with tools like `gdb`, using `sudo gdb` and then `attach <pid>`.
+Then `pidof cosmic-comp` can be used to get the PID of the compositor. Then it is possible to investigate further with tools like `gdb`, using `sudo gdb` then `attach <pid>`.
@@ -14,16 +14,15 @@ build:
    {{ just }} cosmic-idle/build-release
    {{ just }} cosmic-initial-setup/build-release
    {{ just }} cosmic-launcher/build-release
-    {{ just }} cosmic-monitor/build-release
    {{ just }} cosmic-notifications/build-release
-    {{ just }} cosmic-osd/build-release
+    {{ make }} -C cosmic-osd all
    {{ just }} cosmic-panel/build-release
    {{ just }} cosmic-player/build-release
    {{ just }} cosmic-randr/build-release
    {{ just }} cosmic-screenshot/build-release
    {{ just }} cosmic-settings/build-release
    {{ make }} -C cosmic-settings-daemon all
-    {{ just }} cosmic-session/build-release
+    {{ just }} cosmic-session/all
    {{ just }} cosmic-store/build-release
    {{ just }} cosmic-term/build-release
    {{ make }} -C cosmic-wallpapers all
@@ -43,21 +42,20 @@ install rootdir="" prefix="/usr/local": build
    {{ just }} rootdir={{rootdir}} prefix={{prefix}} cosmic-idle/install
    {{ just }} rootdir={{rootdir}} prefix={{prefix}} cosmic-initial-setup/install
    {{ just }} rootdir={{rootdir}} prefix={{prefix}} cosmic-launcher/install
-    {{ just }} rootdir={{rootdir}} prefix={{prefix}} cosmic-monitor/install
    {{ just }} rootdir={{rootdir}} prefix={{prefix}} cosmic-notifications/install
-    {{ just }} rootdir={{rootdir}} prefix={{prefix}} cosmic-osd/install
+    {{ make }} -C cosmic-osd install DESTDIR={{rootdir}} prefix={{prefix}}
    {{ just }} rootdir={{rootdir}} prefix={{prefix}} cosmic-panel/install
    {{ just }} rootdir={{rootdir}} prefix={{prefix}} cosmic-player/install
    {{ just }} rootdir={{rootdir}} prefix={{prefix}} cosmic-randr/install
    {{ just }} rootdir={{rootdir}} prefix={{prefix}} cosmic-screenshot/install
    {{ just }} rootdir={{rootdir}} prefix={{prefix}} cosmic-settings/install
    {{ make }} -C cosmic-settings-daemon install DESTDIR={{rootdir}} prefix={{prefix}}
-    {{ just }} rootdir={{rootdir}} prefix={{prefix}} cosmic-session/install
+    {{ just }} rootdir={{rootdir}} prefix={{rootdir + prefix}} cosmic-session/install
    {{ just }} rootdir={{rootdir}} prefix={{prefix}} cosmic-store/install
    {{ just }} rootdir={{rootdir}} prefix={{prefix}} cosmic-term/install
    {{ make }} -C cosmic-wallpapers install DESTDIR={{rootdir}} prefix={{prefix}}
    {{ make }} -C cosmic-workspaces-epoch install DESTDIR={{rootdir}} prefix={{prefix}}
-    {{ just }} rootdir={{rootdir}} pop-launcher/install
+    {{ just }} rootdir={{rootdir}} prefix={{prefix}} pop-launcher/install
    {{ make }} -C xdg-desktop-portal-cosmic install DESTDIR={{rootdir}} prefix={{prefix}}

 _mkdir dir:
@@ -86,7 +84,6 @@ clean:
    {{ just }} cosmic-idle/clean
    {{ just }} cosmic-initial-setup/clean
    rm -rf cosmic-launcher/target
-    {{ just }} cosmic-monitor/clean
    rm -rf cosmic-panel/target
    rm -rf cosmic-player/target
    rm -rf cosmic-notifications/target
@@ -2,15 +2,14 @@

 set -e

-if [ -z "$1" ]
+TAG="$1"
+
+if [ -z "$TAG" ]
 then
-    echo "$0 [epoch version]" >&2
+    echo "$0 [tag]" >&2
    exit 1
 fi

-VERSION="$1"
-TAG="epoch-$1"
-
 echo "Do you want to tag the current state of cosmic-epoch with the tag $TAG? (y/N)"
 read answer
 if [ "$answer" != "y" ]
@@ -23,8 +22,8 @@ set -x

 git fetch --recurse-submodules

-git tag --force --annotate "$TAG" --message "Epoch ${VERSION}"
-git submodule foreach git tag --force --annotate "$TAG" --message "Epoch ${VERSION}"
+git tag --force "$TAG"
+git submodule foreach git tag --force "$TAG"

 git push --force origin tag "$TAG"
 git submodule foreach git push --force origin tag "$TAG"
@@ -1,47 +0,0 @@
-#!/usr/bin/env bash
-
-set -e
-
-# This should be the _next_ epoch version
-version=1.3.0
-subject="Epoch ${version} version update"
-description="Generated by cosmic-epoch scripts/version-update.sh"
-
-repos=(
-    cosmic-edit
-    cosmic-files
-    cosmic-monitor
-    cosmic-player
-    cosmic-store
-    cosmic-term
-)
-
-for repo in "${repos[@]}"
-do
-    git submodule update --recursive "${repo}"
-    pushd "${repo}"
-    git fetch origin
-    git checkout -B epoch-update origin/master
-    git reset --hard
-    if [ "$(dpkg-parsechangelog --show-field Version)" != "${version}" ]
-    then
-        dch --newversion "${version}" --distribution noble "${subject}"
-    fi
-    cargo set-version "${version}"
-    cargo update
-    git commit -a -m "${subject}" -m "${description}"
-    git push -f -u origin epoch-update
-    pr_url="$(gh pr list --head epoch-update --state open --json url --jq '.[].url')"
-    if [ -n "${pr_url}" ]
-    then
-        echo "PR already open: ${pr_url}"
-    else
-        gh pr create \
-            --title "${subject}" \
-            --body "${description}" \
-            --assignee "@me" \
-            --reviewer "pop-os/engineering" \
-            --reviewer "pop-os/quality-assurance"
-    fi
-    popd
-done