From f802d3bcb5b65c105fd39356fd2bc983c7ded51c Mon Sep 17 00:00:00 2001 From: koru Date: Tue, 29 Sep 2026 18:13:29 +0200 Subject: [PATCH] docs: Update formatting in readme and contributing.md (#1061) Just some `readme.md` and `contributing.md` formatting update and tidy up. Signed-off-by: koru Reviewed-on: https://codeberg.org/fairyglade/ly/pulls/1061 Reviewed-by: AnErrupTion --- contributing.md | 74 ++++++++++++++--- readme.md | 212 ++++++++++++++++++++++++++++++------------------ 2 files changed, 196 insertions(+), 90 deletions(-) diff --git a/contributing.md b/contributing.md index eddaffb..80bfde9 100644 --- a/contributing.md +++ b/contributing.md @@ -1,29 +1,77 @@ -# Contributing to Ly +# Contributing -To contribute to Ly, you have to open a pull request on [Codeberg](https://codeberg.org/fairyglade/ly), as [GitHub](https://github.com/fairyglade/ly) is just a mirror. However, you also have to respect the following rules, otherwise your PR may end up being rejected: +To contribute to Ly, you have to open a pull request on +[Codeberg](https://codeberg.org/fairyglade/ly), as +[GitHub](https://github.com/fairyglade/ly) is just a mirror. However, you also +have to respect the following rules, otherwise your PR may end up being +rejected: ## AI usage -While we cannot control your usage of any LLM whatsoever, we do heavily discourage their use for environmental, ethical & moral reasons that you can learn more about on the Internet. However, if you do end up still using them, here are a couple rules you **must absolutely** respect for your PR not to get instantly shot down. Of course, it goes without saying that **all** the other rules in the other sections below **must** be adhered to, even more so when AI is used. +While we cannot control your usage of any LLM whatsoever, we do heavily +discourage their use for environmental, ethical & moral reasons that you can +learn more about on the Internet. However, if you do end up still using them, +here are a couple rules you **must absolutely** respect for your PR not to get +instantly shot down. Of course, it goes without saying that **all** the other +rules in the other sections below **must** be adhered to, even more so when AI +is used. -1. **Communicate through you**, not the AI; as in, responses to reviews or other comments in the PR must be written by you and not an LLM. If English isn't your native language and you have a lot of trouble speaking it, you _may_ use AI, but responses must not be your typical, alienating AI-generated text: https://github.com/realrossmanngroup/no_ai_slop_writing_rules -2. Control the code, as in, **don't vibecode**, especially if you don't know Zig. Don't waste the maintainers's time, and **heavily test your code**, as AI-generated code is typically more error-prone in subtle ways (even if they can be better than humans in some other aspects). Finally, don't generate any "summary" or whatever the AI may come up with during the process. **If you cannot understand the generated code, do not contribute it**. Maintainers are busy and are often simple volunteers, so the less work they have to do, the better. -3. **Be transparent about AI usage**. Precise what AI model was used in the process, and preferably, how you went about creating your changes (i.e. how did you use AI to make the pull request). The more honest you are about it, the more likely your PR will be accepted and merged into the code base. +1. **Communicate through you**, not the AI; as in, responses to reviews or other + comments in the PR must be written by you and not an LLM. If English isn't + your native language and you have a lot of trouble speaking it, you _may_ use + AI, but responses must not be your typical, alienating AI-generated text: + . +2. Control the code, as in, **don't vibecode**, especially if you don't know + Zig. Don't waste the maintainers's time, and **heavily test your code**, as + AI-generated code is typically more error-prone in subtle ways (even if they + can be better than humans in some other aspects). Finally, don't generate any + "summary" or whatever the AI may come up with during the process. **If you + cannot understand the generated code, do not contribute it**. Maintainers are + busy and are often simple volunteers, so the less work they have to do, the + better. +3. **Be transparent about AI usage**. Precise what AI model was used in the + process, and preferably, how you went about creating your changes (i.e. how + did you use AI to make the pull request). The more honest you are about it, + the more likely your PR will be accepted and merged into the code base. -If all the above rules are respected, your changes have much more likely to be accepted into the code base. +If all the above rules are respected, your changes have much more likely to be +accepted into the code base. ## Code style -You must follow Zig's [style guide](https://ziglang.org/documentation/master/#Style-Guide). In most cases, all you'll have to do is run `zig fmt` after you have completed your changes, though it does not fix everything, notably variable, function & field naming, as well as the maximum length of aline. +You must follow Zig's +[style guide](https://ziglang.org/documentation/master/#Style-Guide). In most +cases, all you'll have to do is run `zig fmt` after you have completed your +changes, though it does not fix everything, notably variable, function & field +naming, as well as the maximum length of aline. -For the former, please refer to the aforementioned style guide in that case. For the latter, you must respect a maximum line length of **80 characters**. For function calls with many parameters or anything similar that may overflow this limit, consider adding a trailing comma to the list so that `zig fmt` can split it into multiple lines. Ideally, few or no lines end up having to get soft wrapped by an editor having this limit set. +For the former, please refer to the aforementioned style guide in that case. For +the latter, you must respect a maximum line length of **80 characters**. For +function calls with many parameters or anything similar that may overflow this +limit, consider adding a trailing comma to the list so that `zig fmt` can split +it into multiple lines. Ideally, few or no lines end up having to get soft +wrapped by an editor having this limit set. ## Commit names & descriptions -1. **Commit names must be descriptive**, resorting to the commit description if they are too long. In such cases, the commit name **must** be shortened while still making sense. With that said, no particular convention (emojis, prefixes & suffixes, etc.) is mandated for them, and you are free to adopt any one you think is best or that you are used to. -2. **Do not force push**, as PRs will get squashed into a single commit anyway. This erases history and makes it impossible to see the changes done over time and by a particular commit. -3. While not a requirement per se, **consider signing your commits** with an SSH or GPG key for security purposes. This ensures to a lesser extent that you are the person who you claim to be, and reduces the potential amount of malicious contributions that could infiltrate the code base. +1. **Commit names must be descriptive**, resorting to the commit description if + they are too long. In such cases, the commit name **must** be shortened while + still making sense. With that said, no particular convention (emojis, + prefixes & suffixes, etc.) is mandated for them, and you are free to adopt + any one you think is best or that you are used to. +2. **Do not force push**, as PRs will get squashed into a single commit anyway. + This erases history and makes it impossible to see the changes done over time + and by a particular commit. +3. While not a requirement per se, **consider signing your commits** with an SSH + or GPG key for security purposes. This ensures to a lesser extent that you + are the person who you claim to be, and reduces the potential amount of + malicious contributions that could infiltrate the code base. ## Additional requirements -Other requirements (such as testing your code) for merging the changes will be available when you open your pull request via the template (which you **must** use), however, these are not stated here because they may not be mandatory in some cases (e.g. if the changes are still work-in-progress), so they may temporarily be ommitted for a certain period of time until the changes are fully ready to be reviewed, for instance. +Other requirements (such as testing your code) for merging the changes will be +available when you open your pull request via the template (which you **must** +use), however, these are not stated here because they may not be mandatory in +some cases (e.g. if the changes are still work-in-progress), so they may +temporarily be ommitted for a certain period of time until the changes are fully +ready to be reviewed, for instance. diff --git a/readme.md b/readme.md index 6073179..d00c593 100644 --- a/readme.md +++ b/readme.md @@ -1,77 +1,92 @@ -# The Ly display manager +# Ly -![Ly screenshot](.github/screenshot.png "Ly screenshot") +![Ly screenshot](.github/screenshot.png) -_Note: the above animation can be found [here](https://codeberg.org/fairyglade/ly-community/src/branch/main/animations/dur/blackhole-smooth-240x67.dur)!_ +_Note: the above animation can be found +[here](https://codeberg.org/fairyglade/ly-community/src/branch/main/animations/dur/blackhole-smooth-240x67.dur)!_ -Ly is a lightweight TUI (ncurses-like) display manager for Linux and BSD, designed with portability in mind and doesn't require systemd to run. +Ly is a lightweight TUI (ncurses-like) display manager for Linux and BSD, +designed with portability in mind and doesn't require systemd to run. -Join us on Matrix over at [#ly-dm:matrix.org](https://matrix.to/#/#ly-dm:matrix.org)! +Join us on Matrix over at +[#ly-dm:matrix.org](https://matrix.to/#/#ly-dm:matrix.org)! > [!NOTE] -> Development happens on [Codeberg](https://codeberg.org/fairyglade/ly) with a mirror on [GitHub](https://github.com/fairyglade/ly). +> +> Development happens on [Codeberg](https://codeberg.org/fairyglade/ly) with a +> mirror on [GitHub](https://github.com/fairyglade/ly). ## Dependencies -- Compile-time: - - zig 0.16.x (you must use a **release version** of zig; check that `zig version` does not have a `-dev*` suffix) +### Compile-time - - libc +- zig 0.16.x (you must use a **release version** of zig; check that `zig + version` does not have a `-dev*` suffix) - - pam +- libc - - xcb (optional, required by default; needed for X11 support) +- pam -- Runtime (with default config): - - xorg +- xcb (optional, required by default; needed for X11 support) - - xorg-xauth +### Runtime (default config) - - brightnessctl +- xorg -### Debian +- xorg-xauth -``` +- brightnessctl + +### Distro-specific + +#### Debian + +```console # apt install build-essential libpam0g-dev libxcb-xkb-dev xauth xserver-xorg brightnessctl ``` -### Fedora +#### Fedora -``` +```console # dnf install kernel-devel pam-devel libxcb-devel zig xorg-x11-xauth xorg-x11-server brightnessctl ``` > [!WARNING] -> Distributions using SELinux such as Fedora and openSUSE Tumbleweed may encounter issues. If you encounter such issues, such as session launch failures, proceed with the following steps: > -> ``` +> Distributions using SELinux such as Fedora and openSUSE Tumbleweed may +> encounter issues. If you encounter such issues, such as session launch +> failures, proceed with the following steps: +> +> ```console > # ausearch -m avc -ts recent > ``` > > If SELinux is denying process context transition, you will see this output: > -> ``` +> ```ini > denied { transition } for pid=XXXX comm="ly" path="/usr/bin/bash" > scontext=system_u:system_r:unconfined_service_t:s0 > tcontext=unconfined_u:unconfined_r:unconfined_t:s0 > tclass=process permissive=0 > ``` > -> Pipe this output into `audit2allow` to generate a security module package. This will persist regardless of changes to filesystem permissions: +> Pipe this output into `audit2allow` to generate a security module package. +> This will persist regardless of changes to filesystem permissions: > -> ``` +> ```console > # ausearch -m avc -ts recent | audit2allow -M ly-local > ``` > -> ``` +> ```console > # semodule -i ly-local.pp > ``` > -> _This fix has been confirmed on Fedora 39 and 44 and openSUSE Tumbleweed. (#494)_ +> _This fix has been confirmed on Fedora 39 and 44 and openSUSE Tumbleweed. +> (#494)_ -### FreeBSD +#### FreeBSD -``` +```console # pkg install ca_root_nss libxcb git xorg xauth ``` @@ -81,7 +96,10 @@ Join us on Matrix over at [#ly-dm:matrix.org](https://matrix.to/#/#ly-dm:matrix. ## Custom animations & user scripts -If you want to pimp your Ly installation even further than what the traditional configuration file allows you to, a [community repository](https://codeberg.org/fairyglade/ly-community) exists containing custom animations & scripts, so go check it out! +If you want to pimp your Ly installation even further than what the traditional +configuration file allows you to, a +[community repository](https://codeberg.org/fairyglade/ly-community) exists +containing custom animations & scripts, so go check it out! ## Support @@ -89,15 +107,22 @@ Every environment that works on other login managers also should work on Ly. - Unlike most login managers Ly has an xinitrc and shell entry. -- If you installed your favorite environment and you don't see it, that's because Ly doesn't automatically refresh itself. To fix this you should restart Ly service (depends on your init system) or the easy way is to reboot your system. +- If you installed your favorite environment and you don't see it, that's + because Ly doesn't automatically refresh itself. To fix this you should + restart Ly service (depends on your init system) or the easy way is to reboot + your system. -- If your environment is still missing then check at `/usr/share/xsessions` or `/usr/share/wayland-sessions` to see if a .desktop file is present. +- If your environment is still missing then check at `/usr/share/xsessions` or + `/usr/share/wayland-sessions` to see if a .desktop file is present. -- If there isn't a .desktop file then create a new one at `/etc/ly/custom-sessions` that launches your favorite environment. These .desktop files can be only seen by Ly and if you want them system-wide you also can create at those directories instead. +- If there isn't a .desktop file then create a new one at + `/etc/ly/custom-sessions` that launches your favorite environment. These + .desktop files can be only seen by Ly and if you want them system-wide you + also can create at those directories instead. - If Xorg sessions don't work then check if your distro compiles Ly with Xorg. -Logs are defined by `/etc/ly/config.lua` or `/etc/ly/config.ini`: +- Logs are defined by `/etc/ly/config.lua` or `/etc/ly/config.ini`: - The session log is located at `~/.local/state/ly-session.log` by default. @@ -107,64 +132,78 @@ Logs are defined by `/etc/ly/config.lua` or `/etc/ly/config.ini`: The procedure for manually building Ly is pretty standard: -``` -$ git clone https://codeberg.org/fairyglade/ly.git -$ cd ly +```console +$ git clone https://codeberg.org/fairyglade/ly.git && cd ly $ zig build ``` -After building, you can (optionally) test Ly in a terminal emulator, although authentication will **not** work: +After building, you can (optionally) test Ly in a terminal emulator, although +authentication will **not** work: -``` +```console $ zig build run ``` > [!IMPORTANT] -> While you can run Ly in a terminal emulator as root, it is **not** recommended. If you want to test Ly, please enable its service (as described below) and reboot your machine. +> +> While you can run Ly in a terminal emulator as root, it is **not** +> recommended. If you want to test Ly, please enable its service (as described +> below) and reboot your machine. > [!NOTE] -> You can, however, test your configuration file changes like that. Note that you must do Ctrl+C in order to exit Ly. +> +> You can, however, test your configuration file changes like that. Note that +> you must do Ctrl+C in order to exit Ly. -The next sections will explain how to use Ly with a variety of init systems. Detailed explanation is only given for systemd, but should be applicable for all. +The next sections will explain how to use Ly with a variety of init systems. +Detailed explanation is only given for systemd, but should be applicable for +all. > [!NOTE] +> > All following sections will assume you are using LightDM for convenience sake. ### systemd Now, you can install Ly on your system: -``` +```console # zig build installexe -Dinit_system=systemd ``` > [!NOTE] +> > The `init_system` parameter is optional and defaults to `systemd`. -Note that you also need to disable your current display manager. For example, if you are using LightDM, you can execute the following command: +Note that you also need to disable your current display manager. For example, if +you are using LightDM, you can execute the following command: -``` +```console # systemctl disable lightdm.service ``` Then, similarly to the previous command, you need to enable the Ly service: -``` +```console # systemctl enable ly@tty2.service ``` > [!IMPORTANT] -> Because Ly runs in a TTY, you **must** disable the TTY service that Ly will run on, otherwise bad things will happen. For example, to disable `getty` spawning on TTY 2, you need to execute the following command: +> +> Because Ly runs in a TTY, you **must** disable the TTY service that Ly will +> run on, otherwise bad things will happen. For example, to disable `getty` +> spawning on TTY 2, you need to execute the following command: -``` +```console # systemctl disable getty@tty2.service ``` -On non-systemd systems, you can change the TTY Ly will run on by editing the corresponding service file for your platform. +On non-systemd systems, you can change the TTY Ly will run on by editing the +corresponding service file for your platform. ### OpenRC -``` +```console # zig build installexe -Dinit_system=openrc # rc-update del lightdm # rc-update add ly @@ -172,11 +211,12 @@ On non-systemd systems, you can change the TTY Ly will run on by editing the cor ``` > [!NOTE] -> On Gentoo, Alpine and potentially others, you also **must** comment out the appropriate line for the TTY in /etc/inittab. +> On Gentoo, Alpine and potentially others, you also **must** comment out the +> appropriate line for the TTY in /etc/inittab. ### runit -``` +```console # zig build installexe -Dinit_system=runit # unlink /var/service/lightdm # ln -s /etc/sv/ly /var/service/ @@ -186,7 +226,7 @@ On non-systemd systems, you can change the TTY Ly will run on by editing the cor ### s6 -``` +```console # zig build installexe -Dinit_system=s6 # s6-rc -d change lightdm # s6-service add default ly-srv @@ -198,98 +238,116 @@ To disable TTY 2, edit `/etc/s6/config/tty2.conf` and set `SPAWN="no"`. ### dinit -``` +```console # zig build installexe -Dinit_system=dinit # dinitctl disable lightdm # dinitctl enable ly ``` -To disable TTY 2, go to `/etc/dinit.d/config/console.conf` and modify `ACTIVE_CONSOLES`. +To disable TTY 2, go to `/etc/dinit.d/config/console.conf` and modify +`ACTIVE_CONSOLES`. ### sysvinit -``` +```console # zig build installexe -Dinit_system=sysvinit # update-rc.d lightdm disable # update-rc.d ly defaults ``` -To disable TTY 2, go to `/etc/inittab` and comment out the line containing `tty2`. +To disable TTY 2, go to `/etc/inittab` and comment out the line containing +`tty2`. ### FreeBSD -``` +```console # zig build installexe -Dprefix_directory=/usr/local -Dconfig_directory=/usr/local/etc -Dinit_system=freebsd # sysrc lightdm_enable="NO" ``` To enable Ly, add the following entry to `/etc/gettytab`: -``` +```bash Ly:\ :lo=/usr/local/bin/ly_wrapper:\ :al=root: ``` -Then, modify the command field of the `ttyv1` terminal entry in `/etc/ttys` (TTYs in FreeBSD start at 0): +Then, modify the command field of the `ttyv1` terminal entry in `/etc/ttys` +(TTYs in FreeBSD start at 0): -``` +```bash ttyv1 "/usr/libexec/getty Ly" xterm on secure ``` ### Updating -You can also install Ly without overriding the current configuration file. This is called **updating**. To update, simply run: +You can also install Ly without overriding the current configuration file. This +is called **updating**. To update, simply run: -``` +```console # zig build installnoconf ``` -You can, of course, still select the init system of your choice when using this command. +You can, of course, still select the init system of your choice when using this +command. ## Configuration -You can find all the configuration in `/etc/ly/config.lua`. The file is fully commented, and includes the default values. +You can find all the configuration in `/etc/ly/config.lua`. The file is fully +commented, and includes the default values. -It uses the Lua language, which means you can make the configuration dynamic. You could, for example, choose a random animation each time Ly starts up. +It uses the Lua language, which means you can make the configuration dynamic. +You could, for example, choose a random animation each time Ly starts up. -You may also check the validity of your configuration file (i.e. if there are any errors in it) with the following command: +You may also check the validity of your configuration file (i.e. if there are +any errors in it) with the following command: -``` +```console $ ly --validate-config /etc/ly/config.lua ``` ## Controls -Use the Up/Down arrow keys to change the current field, and the Left/Right arrow keys to scroll through the different fields (whether it be the info line, the desktop environment, or the username). The info line is where messages and errors are displayed. +Use the Up/Down arrow keys to change the current field, and the Left/Right arrow +keys to scroll through the different fields (whether it be the info line, the +desktop environment, or the username). The info line is where messages and +errors are displayed. ## A note on .xinitrc -If your `.xinitrc` file doesn't work, make sure it is executable and includes a shebang. This file is supposed to be a shell script! Quoting from `xinit`'s man page: +If your `.xinitrc` file doesn't work, make sure it is executable and includes a +shebang. This file is supposed to be a shell script! Quoting from `xinit`'s man +page: -> If no specific client program is given on the command line, xinit will look for a file in the user's home directory called .xinitrc to run as a shell script to start up client programs. +> If no specific client program is given on the command line, xinit will look +> for a file in the user's home directory called .xinitrc to run as a shell +> script to start up client programs. A typical shebang for a shell script looks like this: -``` +```bash #!/bin/sh ``` ## Tips - The numlock and capslock states are printed in the top-right corner. - - Use the F1 and F2 keys to respectively shutdown and reboot. - -- Take a look at your `.xsession` file if X doesn't start, as it can interfere (this file is launched with X to configure the display properly). +- Take a look at your `.xsession` file if X doesn't start, as it can interfere + (this file is launched with X to configure the display properly). ## A final note -The name "Ly" is a tribute to the fairy from the game Rayman. Ly was tested by oxodao, who is some seriously awesome dude. +The name "Ly" is a tribute to the fairy from the game Rayman. Ly was tested by +oxodao, who is some seriously awesome dude. -Also, Ly wouldn't be there today without [ashametrine](https://github.com/ashametrine), who has done significant contributions to the project for the Zig rewrite, which lead to the release of Ly v1.0.0. Massive thanks, and sorry for not crediting you enough beforehand! +Also, Ly wouldn't be there today without +[ashametrine](https://github.com/ashametrine), who has done significant +contributions to the project for the Zig rewrite, which lead to the release of +Ly v1.0.0. Massive thanks, and sorry for not crediting you enough beforehand! ### Donate If you like Ly and wish to support my work further, feel free to donate via my -[Liberapay link](https://liberapay.com/ShiningLea)! +[Liberapay](https://liberapay.com/ShiningLea)!