This is a guideline for contributing to Kaidan. There is also a guide for a basic setup targeted at contributors which are unfamiliar with KDE Identity, GitLab or Git and want to start contributing quickly.
In order to contribute to Kaidan, please create branches on your forked repository and submit merge requests for them. Please do not create branches on Kaidan's main repository or push your commits directly to its master branch.
Use the following prefixes for branch names:
feature/for new features (changes with new behavior)refactor/for changes of the code structure without changing the general behaviorfix/for fixes (changes for intended / correct behavior)design/for design changesdoc/for documentation
Current Maintainers:
- Linus Jahn (@lnj)
- Jonah Brüchert (@jbbgameich)
- Melvin Keskin (@melvo)
They are responsible for accepting MRs. Nevertheless, everybody is welcome to review MRs and give feedback on them.
Please stick to the following steps for opening, reviewing and accepting MRs.
- Create a new branch from the master branch to work on it.
- Write short commit messages starting with an upper case letter and the imperative.
- Split your commits logically.
- Do not mix unrelated changes in the same MR.
- Create an MR with the master branch as its target.
- Add
Draft:in front of the MR's title as long as you are working on the MR and remove it as soon as it is ready to be reviewed. - A maintainer and possibly other reviewers will give you feedback.
- Improve your MR according to their feedback, push your commits and close open threads via the Resolve thread button.
- If necessary, modify, reorder or squash your commits and force-push (
git push -f) the result to the MR's branch. - As soon as all threads on your MR are resolved, a maintainer will merge your commits into the master branch.
Please do not merge your commits into the master branch by yourself. If maintainers approved your MR but have not yet merged it, that probably means that they are waiting for the approval of additional maintainers. Feel free to ask if anything is unclear.
- Provide detailed descriptions of found issues to the author.
- Try to give the author concrete proposals for improving the code via the Insert suggestion button while commenting.
- If the proposals are too complicated, create and push a commit with your proposal to your own fork of Kaidan and open an MR with the author's MR branch as its target.
- In case you are a maintainer:
- If you think that no additional review is needed, make editorial modifications (such as squashing the commits) and merge the result directly.
- If you would like to get (more) feedback from other maintainers, approve the MR using the Approve button and mention other maintainers to review the MR.
- In case you are not a maintainer and you think that the MR is ready to be merged, approve the MR using the Approve button.
Reviews have to be done by at least one maintainer not involved as the MR's author or co-author.
If you add or update a functionality specified by an XMPP Extension Protocol (XEP), adjust the Description of a Project (DOAP) file accordingly.
Kaidan uses a configuration file to store settings such as the last window size.
On Linux, that configuration file is located at .config/kaidan/kaidan.conf.
Kaidan's database is an SQLite file.
It stores, for example, contacts and messages.
On Linux, you can find it at .local/kaidan/kaidan.sqlite3.
To open it, you need an SQLite application (e.g., sqlitebrowser, use sudo apt install sqlitebrowser to install it on Debian-based systems)
There are some configuration options that cannot be set via the user interface and that are mostly useful for testing.
| Name | Type | Description |
|---|---|---|
auth/tlsErrorsIgnored |
bool |
If enabled, invalid certificates are also accepted. |
auth/tlsRequirement |
int |
0: Use TLS if available, 1: Disable TLS, 2: Require TLS |
The environment variable KAIDAN_PROFILE can be set to run Kaidan with custom configuration and database files.
It defines their filename suffixes after a separating - while their file extensions cannot be changed.
In combination with the command-line option --multiple, multiple instances of Kaidan can be run simultaneously with different profiles.
E.g., if you set KAIDAN_PROFILE=test, the configuration file will be kaidan-test.conf and the database file messages-test.sqlite3.
The environment variable QT_LOGGING_RULES controls what is logged.
In order to print all log messages, you can set QT_LOGGING_RULES=im.kaidan.*=true.
You can specify a category and type (i.e., log level) to print only specific log messages via QT_LOGGING_RULES=im.kaidan.<category>.<type>=true (replace <category> and <type> with the desired values).
KDebugSettings can be used as a graphical alternative.
Once you inserted kaidan/build/kaidan.categories, you can manage how to log for Kaidan there.
Kaidan prints QXmpp's log messages as well.
LogHandler specifies the logging type.
QXmpp mainly logs the XML data exchanged between Kaidan and the XMPP servers it is connected to.
The command-line argument --disable-xml-log disables that.
A style influences Kaidan's look.
It can be set via the environment variable QT_QUICK_CONTROLS_STYLE.
Kaidan's default style is org.kde.desktop.
You can run Kaidan using Android's Material style with QT_QUICK_CONTROLS_STYLE=Material kaidan.
Kaidan can be run on desktop devices as well as on mobile devices with touchscreens.
A user interface optimized for mobile devices can be applied via the environment variable QT_QUICK_CONTROLS_MOBILE.
You can run Kaidan with QT_QUICK_CONTROLS_MOBILE=true kaidan in order to get its mobile view.
Kaidan complies with KDE's coding style. All code changes are automatically formatted by KDE's Git pre-commit hook.
C++ files (except unit tests) are stored in Kaidan's src directory.
If you add such a new file, please add it to the related CMakeLists file.
Kaidan uses QML for its user interface. New QML files must be added to the related Qt resource collection file. You can add your file to the end of the listings without applying any order. Please do not change the order of existing files.
Please use let or const instead of var when you define a variable in JavaScript within a QML file.
Kaidan depends on the user interface framework Kirigami.
Please use its visual components within Kaidan instead of creating own ones as far as it makes sense.
You can have a look at the components Kirigami provides by opening the Kirigami Gallery (use sudo apt install kirigami-gallery to install it and kirigami2gallery to run it on Debian-based systems).
Kaidan is translated via KDE Localization.
In order to make translations possible, you need to use qsTr("<text>") (Example: qsTr("Login")) for QML string's and tr(<text>) (Example: tr("Online")) for QStrings in C++.
For using an icon as a user interface element such as Kirigami.Icon or QtQuick.Controls.Button, you need to set the actual icon as its source resp. name property.
All icons used by Kaidan must be referenced in the related Qt resource collection file.
Kaidan's default icon theme is Breeze.
Instead of using new icons, search and use icons that are already used for similar purposes.
If your purpose needs a new icon that is not yet used by Kaidan, you can find one with Icon Explorer (use sudo apt install plasma-sdk to install it and iconexplorer to run it on Debian-based systems).
Via corresponding buttons, you can check whether an icon is available for Breeze and if so, retrieve the icon's name to be used in Kaidan's code and the icon's path to be used in the related Qt resource collection file.
Always make sure that you use the right path within Breeze's icon directory. Cuttlefish will open the chosen icon of your system's theme. If that is not Breeze, you need to find the corresponding icon in Breeze's icon directory and use that path.
The system Kaidan is run on can apply a different icon theme than Kaidan's default.
For good compatibility with various icon themes, it is often better to use the -symbolic.svg variant of an icon.
The preferred format for graphics in Kaidan is SVG. If SVG is not applicable like for screenshots, the graphic should have the format PNG. New graphics that are used at runtime must be added to the related Qt resource collection file.
If you change a graphic, it might be necessary to run graphic rendering tool in order to generate new PNG files from their original SVG files. Once the PNG files are created, the graphics need to be updated everywhere they are used (e.g., on Mastodon or in Kaidan's group chat).
In any case, the new or modified graphic must be optimized before adding it to a commit.
The license file must be updated if there are copyright changes:
- Add to the license generation tool a new
CopyrightTargetfor a new graphic or change an existing one for a modification of an existing graphic. - Execute
utils/generate-license.py > LICENSEfor updating the license file file. - Add those two file changes to the same commit which contains the new or modified graphic.
If the logo is changed, it has to be done in a separate commit. Furthermore, the logo has to be updated on multiple other places:
- For this GitLab project by creating a sysadmin request and providing a link to a PNG version in its description.
- In the repository of Kaidan's website by updating all instances of
favicon*andlogo*. - On Kaidan's Mastodon profile by uploading a new avatar.
- In Kaidan's group chat by uploading a new avatar.
Other files that are used at runtime must be added to the related Qt resource collection file. The XMPP provider list from XMPP Providers is an example for such a file.
Notifications are triggered via KNotifications. The configuration file is used by KNotifications. It is automatically installed when you install Kaidan. Remember to install Kaidan again if you modified that file in order to see any changes.
Unit tests are stored in Kaidan's tests directory.
If you add a new C++ file to that directory, please add it to the related CMakeLists file.
In order to build the unit tests, you need to enable the CMake build option BUILD_TESTS (i.e., add -DBUILD_TESTS=ON to the cmake command for building Kaidan).
On a daily basis, Kaidan is automatically built for various systems.
Those nightly builds are based on Kaidan's master branch.
Kaidan is packaged for several Linux distributions.
For distributions supporting Flatpak, there is a Flatpak configuration (called manifest) for nightly builds.
The builds are created by including a corresponding file in Kaidan's GitLab CI/CD configuration which triggers the flatpak job.
There is also a Flatpak configuration for stable builds on Flathub.
See KDE's Flatpak documentation for more information.
In addition, there is a KDE Craft configuration (called blueprint) for Windows builds.
Dependencies are mainly managed by Kaidan's root CMakeLists file. When you add or remove dependencies, update the README and the building guides as well.
You also need to modify the KDE Craft and Flatpak configuration files for Kaidan.
Only dependencies that are not configured by KDE's Flatpak runtime via its file org.kde.Sdk.json.in, need to be added to Kaidan's Flatpak configuration.
It is sometimes needed to update the KDE Craft configurations for QXmpp and libomemo-c as well.
That way, Kaidan can be built correctly by KDE's automated process.
As soon as the configuration files are updated and Kaidan is automatically built, the corresponding files can be downloaded.
Kaidan's releases are marked by tags. For each release, its source code and the source code's signature is uploaded by one of Kaidan's maintainers.
Make sure that your public OpenPGP key is added to the release keyring. It allows others (especially KDE's administrators) to verify your signature.
Kaidan's repository information must be kept up-to-date. E.g., the branches for translations/releases and the repository's description are configured there.