Warning, /plasma/kwin/CONTRIBUTING.md is written in an unsupported language. File is not indexed.
0001 # Contributing to KWin 0002 0003 ## Chatting 0004 0005 Come on by and ask about anything you run into when hacking on KWin! 0006 0007 KWin's Matrix room on our instance is located here: https://matrix.to/#/#kwin:kde.org. 0008 You can grab an Matrix account at https://webchat.kde.org/ if you don't already have one from us or another provider. 0009 0010 The Matrix room is bridged to `#kde-kwin` on Libera, allowing IRC users to access it. 0011 0012 ## What Needs Doing 0013 0014 There's a large amount of bugs open for KWin on our [Bugzilla instance](https://bugs.kde.org/describecomponents.cgi?product=kwin). 0015 0016 ## Where Stuff Is 0017 0018 Everything codewise for KWin itself is located in the `src` directory. 0019 0020 ### Settings Pages / KCMs 0021 0022 All the settings pages for KWin found in System Settings are located in `src/kcmkwin`. 0023 0024 ### Default Decorations 0025 0026 The Breeze decorations theme is not located in the KWin repository, and is in fact part of the [Breeze repository here](https://invent.kde.org/plasma/breeze), in `kdecoration`. 0027 0028 ### Tab Switcher 0029 0030 The default visual appearance of the tab switcher is not located in the KWin repository, and is in fact part of [Plasma Workspace](https://invent.kde.org/plasma/plasma-workspace), located at `lookandfeel/contents/windowswitcher`. 0031 0032 Other window switchers usually shipped by default are located in [Plasma Addons](https://invent.kde.org/plasma/kdeplasma-addons), located in the `windowswitchers` directory. 0033 0034 ### Window Management 0035 0036 Most window management stuff (layouting, movement, properties, communication between client<->server) is defined in files ending with `client`, such as `x11client.cpp` and `xdgshellclient.cpp`. 0037 0038 ### Window Effects 0039 0040 Window effects are located in the `effects` folder in `src`, with one folder per effect. 0041 Not everything here is an effect as exposed in the configuration UI, such as the colour picker in `src/effects/colorpicker`. 0042 0043 ### Scripting API 0044 0045 Many objects in KWin are exposed directly to the scripting API; scriptable properties are marked with Q_PROPERTY and functions that scripts can invoke on them. 0046 0047 Other scripting stuff is located in `src/scripting`. 0048 0049 ## Conventions 0050 0051 ### Coding Conventions 0052 0053 KWin's coding conventions are located [here](doc/coding-conventions.md). 0054 0055 KWin additionally follows [KDE's Frameworks Coding Style]((https://techbase.kde.org/Policies/Frameworks_Coding_Style)). 0056 0057 ### Commits 0058 0059 We usually use this convention for commits in KWin: 0060 0061 ``` 0062 component/subcomponent: Do a thing 0063 0064 This is a body of the commit message, 0065 elaborating on why we're doing thing. 0066 ``` 0067 0068 While this isn't a hard rule, it's appreciated for easy scanning of commits by their messages. 0069 0070 ## Contributing 0071 0072 KWin uses KDE's GitLab instance for submitting code. 0073 0074 You can read about the [KDE workflow here](https://community.kde.org/Infrastructure/GitLab). 0075 0076 ## Running KWin From Source 0077 0078 KWin uses CMake like most KDE projects, so you can build it like this: 0079 0080 ```bash 0081 mkdir _build 0082 cd _build 0083 cmake .. 0084 make 0085 ``` 0086 0087 People hacking on much KDE software may want to set up [kdesrc-build](https://invent.kde.org/sdk/kdesrc-build). 0088 0089 Once built, you can either install it over your system KWin (not recommended) or run it from the build directory directly. 0090 0091 Running it from your build directory looks like this: 0092 ```bash 0093 # from the root of your build directory 0094 0095 cd bin 0096 0097 # for wayland, starts nested session: with console 0098 0099 env QT_PLUGIN_PATH=`pwd` dbus-run-session ./kwin_wayland --xwayland konsole 0100 0101 # or for x11, replaces current kwin instance: 0102 0103 env QT_PLUGIN_PATH=`pwd` ./kwin_x11 --replace 0104 0105 ``` 0106 0107 QT_PLUGIN_PATH tells Qt to load KWin's plugins from the build directory, and not from your system KWin. 0108 0109 The dbus-run-session is needed to prevent the nested KWin instance from conflicting with your session KWin instance when exporting objects onto the bus, or with stuff like global shortcuts. 0110 0111 If you need to run a whole Wayland plasma session, you should install a development session by first building [plasma-workspace](https://invent.kde.org/plasma/plasma-workspace) and executing the `login-sessions/install-sessions.sh` in the build directory. This can be done using kdesrc-build. 0112 0113 ```bash 0114 kdesrc-build plasma-workspace 0115 # assuming the root directory for kdesrc-build is ~/kde 0116 bash ~/kde/build/plasma-workspace/login-sessions/install-sessions.sh 0117 ``` 0118 Then you can select the develop session in the sddm login screen. 0119 0120 You can look up the current boot kwin log via `journalctl --user-unit plasma-kwin_wayland --boot 0`. 0121 0122 ## Using A Debugger 0123 0124 Trying to attach a debugger to a running KWin instance from within itself will likely be the last thing you do in the session, as KWin will freeze until you resume it from your debugger, which you need KWin to interact with. 0125 0126 Instead, either attach a debugger to a nested KWin instance or debug over SSH. 0127 0128 ## Tests 0129 0130 KWin has a series of unit tests and integration tests that ensure everything is running as expected. 0131 0132 If you're adding substantial new code, it's expected that you'll write tests for it to ensure that it's working as expected. 0133 0134 If you're fixing a bug, it's appreciated, but not expected, that you add a test case for the bug you fix. 0135 0136 You can read more about [KWin's testing infrastructure here](doc/TESTING.md).