Initial commit.

2026-06-02 17:29:55 -04:00
commit db522d7d66
33 changed files with 4017 additions and 0 deletions
@@ -0,0 +1,40 @@
+# Repository Guidelines
+
+## Project Structure & Module Organization
+
+I38Lock is an accessible C screen-locking utility based on i3lock. Core sources live at the repository root: `i3lock.c` handles the main program, while `xcb.c`, `randr.c`, `dpi.c`, `unlock_indicator.c`, and `accessibility_feedback.c` separate display, UI, and screen-reader concerns. Public project headers are under `include/`. The PAM service file is `pam/i38lock`, the manual page is `i38lock.1`, and packaging or CI support lives in `meson/`, `ci/`, and `.github/`.
+
+## Build, Test, and Development Commands
+
+Install the dependencies listed in `README.md`, then build out of tree:
+
+```sh
+meson setup build -Dprefix=/usr
+ninja -C build
+```
+
+To reproduce CI's stricter compile check, configure a fresh build directory:
+
+```sh
+CFLAGS="-Wformat -Wformat-security -Wextra -Wno-unused-parameter -Werror" meson setup build-ci
+ninja -C build-ci
+```
+
+Run `nix develop` first if using the provided Nix development shell. Avoid installing from a development build unless installation behavior is the focus of the change.
+
+## Coding Style & Naming Conventions
+
+The project uses C11 and the checked-in `.clang-format`. Use four-space indentation, braces for control statements, and existing snake_case naming patterns. Format C sources and headers with:
+
+```sh
+clang-format-15 -i $(git ls-files '*.c' 'include/*.h')
+clang-format-15 --dry-run --Werror $(git ls-files '*.c' 'include/*.h')
+```
+
+## Testing Guidelines
+
+There is no automated runtime test suite. Every change must compile with the strict warning flags above. For behavior changes, run `timeout --foreground 30s build/i38lock -n` from an X11 session, verify the affected workflow, then unlock by entering your password and pressing Enter. Install `pam/i38lock` first and keep the watchdog enabled to avoid locking yourself out of an active development session.
+
+## Commit & Pull Request Guidelines
+
+Recent commits use short imperative subjects, often scoped when useful, such as `meson: use explicit_bzero if it is available`. Keep each commit focused. Pull requests should explain the behavior change, include reproduction and verification steps, and link relevant issues. Include `i38lock --version` and environment details for bug fixes. Do not propose image-manipulation features; preprocess background images with external tools.