Skip to content

Latest commit

 

History

History
163 lines (128 loc) · 7.31 KB

CONTRIBUTING.md

File metadata and controls

163 lines (128 loc) · 7.31 KB
Raw

Contributing to KDisplay

Logging and Debugging

The first step in contributing to the project either by providing meaningful feedback or by sending in patches is always the analysis of the runtime behavior of the program.

For KDisplay this means studying the debug log of it being daemonized as a module of the KDE daemon and being run as the interactive KCM. Additionally under normal operation the log of Disman's D-Bus backend launcher process should be read out. To do all that some processes must be started from different terminal windows.

Runtime logging

Preparations

At first the lines

disman*=true
kdisplay*=true

should be added to the file $HOME/.config/QtProject/qtlogging.ini (create the file if it does not exist already). This enables much more debug log to be shown.

Disman D-Bus service

Disman by default starts a suitable backend as a D-Bus service when being asked to by library consumers like KDisplay. To get debug output from this service restart it:

    killall -9 disman_backend_launcher ; /usr/lib/libexec/disman_backend_launcher

For more information on logging Disman's D-Bus backend service see Disman's documentation.

Alternatively a KDisplay executable component (KDED module or KCM) can be started with the Disman backend being run in the component's own process by setting the environment variable DISMAN_IN_PROCESS beforehand. More on this below.

KDE Daemon module

The KDE Daemon (KDED) process that executes the KDisplay daemon module can be restarted with:

    killall -9 kded5 ; kded5

This should give you already plenty of output showing how the KDisplay module is initialized and informed about the current output configuration. And possibly how the module tries to apply another configuration in case the device is a laptop with its lid closed or in a docking station.

The environment variable DISMAN_IN_PROCESS can be set before starting the KDED process what will output all Disman and KDisplay daemon module log lines into the same terminal window but the synchronization with changes from other Disman consumers will only be partial. Therefore it is not recommended in general.

KConfig Module (KCM)

The KDisplay KConfig Module (KCM) provides a frontend UI for users to manipulate the current display configuration. It can either be started from the respective entry in the KDE System Settings or from a terminal by executing the command:

kcmshell5 kcm_kdisplay

As with the KDED module the environment variable DISMAN_IN_PROCESS can be set for printing the KCM log together with the Disman backend log in the same terminal window. As long as no other process is manipulating the display configuration at the same time this can be done without synchronization issues. But in case a disman_backend_launcher process was running in the same D-Bus session it is recommended to shut it down before that.

Accessing the Wayland compositor log

If you debug KDisplay in a Wayland session it is often helpful to also get the debug output of the Wayland compositor. How this can be achieved depends on the compositor.

For Theseus' Ship see the respective section in its documentation on runtime logging.

Debugging with GDB

In case the KDE daemon or the KDisplay KCM crash, the GNU Debugger (GDB) can often provide valuable information about the crash in the form of a backtrace.

For more information see Theseus' Ship's documentation about GDB. Most of it can be applied to applications making use of Disman directly and that often in an easier fashion. For example for starting KDisplay directly with GDB simply issue from a terminal emulator in your desktop session the command:

gdb --ex r --args kcmshell5 kdisplay

Submission Guideline

Contributions to KDisplay are very welcome but follow a strict process that is layed out in detail in Wrapland's contributing document.

Summarizing the main points:

  • Use pull requests directly for smaller contributions, but create issue tickets beforehand for larger changes.
  • Adhere to the KDE Frameworks Coding Style.
  • Pull requests have to be posted against master or a feature branch. Commits to the stable branch are only cherry-picked from the master branch after some testing on the master branch.

Commit Message Guideline

The Conventional Commits 1.0.0 specification is applied with the following amendments:

  • Only the following types are allowed:
    • build: changes to the CMake build system, dependencies or other build-related tooling
    • ci: changes to CI configuration files and scripts
    • docs: documentation only changes to overall project or code
    • feat: new feature
    • fix: bug fix
    • perf: performance improvement
    • refactor: rewrite of code logic that neither fixes a bug nor adds a feature
    • style: improvements to code style without logic change
    • test: addition of a new test or correction of an existing one
  • Only the following optional scopes are allowed:
    • kcm
    • kded
    • plasmoid
  • Angular's Revert and Subject policies are applied.

Example

fix(kcm): provide correct return value

For function exampleFunction the return value was incorrect.
Instead provide the correct value A by changing B to C.

Tooling

See Wrapland's documentation for available tooling.