Contributing

Contributing

Aphotic-Hypr is a full custom Quickshell desktop environment for Hyprland — bar, launcher, notifications, OSD, lock, session menu, dashboard, and area picker are all first-party, not wrappers around third-party tools. Contributions are welcome, but should fit the conventions already established so the project stays uniform as more hands touch it.

Getting started

git clone https://github.com/T-Crypt/Aphotic-Hypr.git
cd Aphotic-Hypr

For where the pieces live — install.sh, profiles/, Configs/, the Quickshell shell's internal layout — see Architecture rather than re-deriving it from the tree; it's covered there in depth.

A typical contribution is a short-lived branch off dev (e.g. fix/short-description), opened as a pull request into dev. dev collects the work for the next release; a release is one dev → main pull request, then a tag on main. Both branches are protected — all changes land through review with CI (tests, shellcheck, bash-syntax, CodeQL) required to pass before merge. ./install.sh --channel edge installs follow dev; the default stable channel installs the newest tag. Changes touching install.sh or a systemd unit also need a real run on the project's dev VM before merging, on top of CI.

Reporting issues

1. Check if it's already reported in GitHub Issues.
2. Open a new issue with a clear description and, for bugs, steps to reproduce.
3. Include your system info (Arch version, Hyprland version).

Full conventions

The detailed, authoritative rules — branch model, QML module conventions, aphotic CLI conventions, installer conventions, verification steps, and scope boundaries — live in one place only: CONTRIBUTING.md in the repo. Read it before opening a PR. In short, it covers:

• Branch model — short-lived branches off dev, PR-gated and CI-enforced; dev → main for a release.
• Module conventions (QML) — singleton/component split, qmldir wiring, the IPC-toggle pattern for overlays, and the Tokens/Config/Settings layering (don't invent a parallel config or token system).
• CLI conventions — one file per aphotic subcommand, shared globalcontrol.sh helpers, and the shared three-way theme/wallpaper/scheme state contract.
• Installer conventions — install.sh must stay idempotent, new shell dependencies go in both profiles/base/full.toml and minimal.toml, and install/uninstall/CLI changes need a test under tests/.
• Live verification — this project verifies against a running shell (qs -c aphotic restart, log check, grim screenshot for visual changes), not just "it parses."
• Scope boundaries — Arch/AUR-only, no fingerprint/face auth, no native C++ plugin dependencies.

Adding new pieces

A few things that aren't covered by CONTRIBUTING.md because they're more "where does this go" than "what's the convention":

• New theme — a directory under ~/.config/awww/<name>/ with a theme.toml manifest and one or more wallpapers; every field is a pin with a sane fallback, so a theme only needs to declare what it wants different from the default. See themes/THEME_SPEC.md for the full contract and Theming for the generation pipeline.
• New profile — add profiles/base/<name>.toml following the shape of minimal.toml/full.toml. See Profiles & Layers.
• New layer — add profiles/layers/<name>.toml; layers are additive and deduplicate automatically against the base profile and each other.
• New aphotic command — add Configs/.local/lib/aphotic/commands/cmd_<name>.sh; it's auto-discovered from its @cmd/@cmd.desc/@cmd.group/@cmd.opt header annotations, no registration step needed. Commands with their own sub-verbs (like play) use a commands/<name>/ subdirectory instead — see CLI Reference.

See also

• Architecture — repo layout and how installation resolves a plan.
• CLI Reference — the full aphotic command surface.
• Profiles & Layers — what each profile/layer installs.
• Theming — the wallust-driven color pipeline.
• Getting Started — the user-facing install walkthrough.

Questions about whether something fits the project's direction are welcome as an issue before you write code.