Contributing

How issues, patches, and bigger design changes land in Phosphor.

Before you open anything

Bugs and small fixes: open an issue or a PR directly. PRs are welcome even without a preceding issue if the change is under about 100 lines and the intent is obvious from the diff.
New features, API changes, new libraries: open an issue first. Cross-library refactors and public-contract changes benefit from a short design discussion before someone writes the code.
Security-sensitive changes (D-Bus surfaces, sandbox hardening, config-loading paths): flag them in the issue so review gets scoped correctly.

Code style

Full conventions live in CONTRIBUTING.md. The shape of them:

C++20, namespace PlasmaZones, explicit on single-arg constructors, override on every virtual.
Naming: PascalCase classes, camelCase functions, m_ prefix on QObject members (POD structs take plain camelCase). Signals are past tense (layoutChanged), slots are action verbs (saveLayout). Emit signals only when the value actually changes.
Qt6 string literals: QLatin1String() for JSON keys and string comparisons, QStringLiteral() for constants, MIME types, and paths. Raw "..." with QString / QJsonObject doesn't compile.
Ownership: parent-based for QObjects; std::unique_ptr or QPointer otherwise. No manual delete.
SPDX headers on every file; #pragma once on every C++ header. License tier is path-dependent: src/**, kcm/**, kwin/**, and tests/** are GPL-3.0-or-later; libs/phosphor-*/** are LGPL-2.1-or-later so third-party plugins can link them without inheriting GPL.
Keep files under 800 lines. Prefer bindings over JS assignments in QML. Kirigami.Theme / Kirigami.Units for colors and spacing, never hardcoded.
Pre-commit hooks handle clang-format and qmlformat. Don't fight them.

Build and test

git clone https://github.com/fuddlesworth/PlasmaZones
cd PlasmaZones
mkdir build && cd build
cmake .. -DCMAKE_BUILD_TYPE=Debug
cmake --build . -j$(nproc)
ctest --output-on-failure

For an install instead of a dev build: -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=/usr then sudo cmake --install .. For a portable build without KDE framework deps (daemon plus editor, no KCM), add -DUSE_KDE_FRAMEWORKS=OFF.

Tests use Qt Test (QTEST_MAIN, QCOMPARE, QVERIFY). Test behavior rather than implementation; mock D-Bus for daemon tests. Edge cases around zones (empty layouts, overlapping zones, invalid coordinates) tend to be where regressions hide.

Translations

UI strings are extracted with a CMake target, not edited by hand:

cmake --build build --target update-ts

This walks C++ and QML sources for calls wrapped in the translation helpers and updates the .ts files under translations/. Two important rules about which helper to use:

In C++, call PzI18n::tr(). Never use KLocalizedString, i18n(), or i18nc() in C++ code; those are QML-only here. The portable build ships without KDE Frameworks, so C++ i18n goes through Phosphor's own wrapper.
In QML, use i18n() and i18nc() via the PzLocalizedContext provided in component scope.

Commits

No mandated prefix list. The rule in CONTRIBUTING.md is "one logical change per commit" with a short summary on the first line and, optionally, a body explaining why. Every new file needs SPDX headers:

// SPDX-FileCopyrightText: 2026 YourName
// SPDX-License-Identifier: GPL-3.0-or-later

AI-assisted commits carry a Co-Authored-By: trailer naming the tool. The AI disclosure page covers the review loop and how the trailer is worded.

Pull request flow

Branch from main.
Before pushing, run the AI review loop. It catches most of what a reviewer would; see the AI-disclosure page for setup.
Open the PR. CI runs the full test suite on Linux. Fix anything red.
A human reviewer signs off. The human who merges owns the regression if one ships.

Where to file what

PlasmaZones app bugs, feature requests, and any phosphor-* library bugs: fuddlesworth/PlasmaZones/issues. The libraries are git-subtree extractable but currently live in the PlasmaZones monorepo, so one issue tracker covers them all.
Brand assets (logos, palette): phosphor-works/branding.
This website: phosphor-works.github.io.

Licensing

Opening a pull request agrees that your contribution ships under the same license as the target repo: GPL-3.0-or-later for PlasmaZones; LGPL-2.1-or-later for the phosphor-* libraries marked for linking from non-GPL code; CC-BY-SA 4.0 for brand assets. The About page has the full breakdown and rationale for the split.