Contributing and security
Where to report issues, how pull requests are reviewed, the local checks to run and the security policy.
Contributions are welcome across the organization. Each repository owns one concern, so the first step is always picking the right one. There is no CI: every repository ships a local check script and the maintainer runs it before pushing, so please run the same checks before opening a pull request.
Where to report
Open the issue in the repository that owns the behavior:
| Topic | Repository |
|---|---|
Installation, updates, packages, login theme, dots plugins |
dots |
| Compositor config, keybinds, scripts | hyprland |
| niri compositor config, scripts, session/portals | niri |
| niri stack install/update, overlays, session entry | niri-meta |
| Compositor-neutral shell and Nyx overlays | niri-shell, nyx-niri |
| Bar, panels, widgets, editor | shell |
| Mascots, island/notch, dock | nyx |
| Wallpapers, scenes, picker | davinci, background |
| Colors and theming | palettes, theme-sync |
| Time, weather, calendar | timex |
| Plugin standard, hub, registry, converted plugins | plugins |
| Manifest schema, API version, compatibility | plugin-api |
PluginHost, Settings, surfaces, Lua mod |
plugin-sdk |
| Plugin architecture and migration notes | transformpath |
| Terminal settings UI | xturing |
| Scene engine and wallpaper daemon | x-ports/xwww |
If you are not sure, use the organization-wide issue template and pick the
component there. Support channels and the code of conduct live in
hyprland (SUPPORT.md,
CODE_OF_CONDUCT.md), and the organization profile summarizes the stack.
Pull requests
- Keep the change focused: one topic per pull request.
- Use the existing commit style (
feat:,fix:,docs:,chore:,ci:) with a short imperative subject. - Run the checks of every repository you touch.
- Update the repository
CHANGELOG.mdwhen it exists; releases are cut from those entries. - New files default to the license already used by the repository: code is MIT-style unless stated otherwise; wallpapers and documentation follow the background terms.
Local checks
| Repository | Command |
|---|---|
| shell | scripts/check.sh |
| hyprland | scripts/check.sh |
| niri | scripts/check.sh |
| niri-meta | dotsniri doctor --self-test |
| palettes | scripts/check.sh |
| theme-sync | scripts/check.sh |
| xturing | scripts/check.sh |
| plugins | tests/smoke.sh |
| plugin-api | compat evaluator fixtures |
| plugin-sdk | qmllint + Lua tests |
- Shell:
qmllintover every.qmlfile andnode --checkover the JS modules. - Hyprland:
luac -pover every Lua config module andbash -nover the scripts (shellcheckis used as an advisory when installed). - niri:
bash -nover the scripts and KDL brace-balance checks; runniri validate -c ~/.config/niri/config.kdlon a machine with niri. - niri-meta:
dotsniri doctor --self-testrunsbash -nover the toolkit and works without niri installed. - Palettes: schema validation plus
index.jsonconsistency. - theme-sync:
compilealland a CLI smoke test (--list,--dry-run). - xturing:
cargo fmt --check, clippy with-D warningsand the tests. - plugins: the smoke harness checks manifests,
qmldirimports, scan resolution, duplicate ids and registry consistency. - plugin-api: the bash and Lua semver evaluators must agree on the shared fixtures.
- plugin-sdk: validate the QML host kit and run the Lua
modtests.
Style guidelines
- Documentation is written in English.
- Configurations and scripts stay palette-driven: read the active palette instead of hardcoding colors.
- Prefer the small existing helpers of each repository over new dependencies.
- For xwww scenes, stay inside the documented sandbox: local assets only, no timers, no network, change-driven redraws.
- For plugins, keep the feature self-contained: the manifest is the only contract, the plugin owns its UI, settings, defaults and scripts, and hosts must never learn plugin ids. Do not copy external plugin repositories into the hub; reference them by source.
Security policy
Do not open a public issue for a security problem. Use GitHub's private reporting instead:
- Open the affected repository and go to Security -> Report a vulnerability (GitHub Security Advisories), or contact the maintainer listed in the repository.
- Include the affected component and version, a description of the impact and a reproduction if you have one.
- You will get an acknowledgement as soon as possible and credit in the advisory once a fix is published.
Scope
The stack runs in the user's session and installs system pieces: packages, the
SDDM theme and /etc/pam.d/quickshell. Reports about the shell, the Hyprland
scripts, the installers, the plugin loader, the wallpaper engine or the scene
runtime are welcome.
Scenes execute user-authored code in the xwww client by design; the runtime
sandbox (memory and stack limits, frame timeout, no I/O, local assets only) is
documented in equisdots/x-ports.
Supported versions
Only the latest release of each repository receives fixes. dots update
keeps an installation on the current releases, and dots doctor reports what
is out of sync. See Updating and diagnosing.
Practical tips
- Test installers before running them on a machine you care about; they use sudo and change system configuration.
- Review scripts before forking or sharing them; personal configs may contain paths or tokens.
- Use xturing's dry mode or a copied
settings.jsonwhen experimenting with options. - Validate palettes before submitting them:
python3 tools/validate_palettes.pyin the palettes repository.
Related pages
- Architecture and repositories for the layout and contracts.
- Updating and diagnosing for the update flow.