[TOC]
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:
- Melvin Keskin (@melvo)
- Filipe Azevedo (@fazevedo)
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.
- Mark the MR as draft as long as you are working on the MR and mark it as ready as soon as it should 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.
E.g., if you set KAIDAN_PROFILE=test, the configuration file will be kaidan-test.conf and the database file messages-test.sqlite3.
In combination with the command-line option --multiple, multiple instances of Kaidan can be run simultaneously with different profiles.
Kaidan stores passwords in an unencrypted file if no password manager is available.
By using the --unencrypted-keychain command-line option, you can force that behavior even if a password manager is available.
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).
Log messages containing any of the strings defined in the environment variable KAIDAN_LOG_FILTER are filtered out of the log.
The strings need to be separated by semicolons (e.g., KAIDAN_LOG_FILTER=a log message part;another log message part).
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.
You can disable that by setting QT_LOGGING_RULES=im.kaidan.xmpp.*=false.
LogHandler specifies the QXmpp-specific logging type.
QXmpp mainly logs the XML data exchanged between Kaidan and the XMPP servers it is connected to.
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.
Kaidan complies with REUSE. Each file has a copyright notice. Such a notice contains the first year a contributor edited the corresponding file.
Once a contributor created a new file or made a significant change to an existing one, a copyright notice has to be added. No additional copyright notice should be added to existing files with a CC0 license.
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_TESTING (i.e., add -DBUILD_TESTING=ON to the cmake command for building Kaidan).
Dependencies are mainly managed by Kaidan's root CMakeLists file. When you add, update or remove dependencies, update the README and the building guides as well.
Kaidan is packaged for several operating systems.
The GitLab templates in Kaidan's GitLab CI/CD configuration automatically run jobs to check whether Kaidan can be built on the following operating systems:
- Android: Dependencies
- FreeBSD: Dependencies
- Linux with latest stable Qt version: Dependencies
- Linux with upcoming Qt version: Dependencies
- Windows: Dependencies
Software on KDE Invent that runs one of the mentioned GitLab jobs for its own default branch is available as a dependency via the same job for Kaidan too. In all other cases, the software needs to be added as a dependency in the referenced files.
To get the most up-to-date state of Kaidan or if the operating system does not provide a regular package, Kaidan is available for Flatpak as well.
There is a local Flatpak configuration (called manifest).
It can be used to build Kaidan based on the repository's current state.
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 manifest.
The repository's current state is automatically built by including a GitLab Flatpak template in Kaidan's GitLab CI/CD configuration.
The resulting flatpak job uses the local manifest and is run on any branch that changes it.
You can download Flatpak builds for a specific branch via https://invent.kde.org/<user>/kaidan/-/jobs/artifacts/<branch>/raw/kaidan.flatpak?job=flatpak (replace <user> and <branch> with the desired values).
Alternatively, you can navigate to the Flatpak build via the corresponding CI job page and its Job artifacts section.
Once downloaded, you can install it for the current user via flatpak install --user <download directory>/kaidan.flatpak (replace <download directory> with the desired value).
After installing Kaidan, it can be run via flatpak run --user im.kaidan.kaidan.
Environment variables can be passed via --env="<variable>=<value>" (replace <variable> and <value> with the desired values).
To remove Kaidan, execute flatpak remove --user im.kaidan.kaidan.
In addition, the flatpak job is run on each change of the master branch.
That latest development state is available via Kaidan's Nightly Flatpak repository.
There is also a Flatpak configuration for stable builds on Flathub. See KDE's Flatpak documentation for more information.
There is a KDE Craft configuration (called blueprint).
That is used to automatically build the master branch for the following systems:
It is sometimes needed to update the blueprints for QXmpp and libomemo-c. If there is no blueprint for a dependency in the KDE Craft Blueprints repository, a new blueprint needs to added before it can be added as a dependency to Kaidan's blueprint. 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.
The release tool releases a new version of Kaidan. Before running the tool, 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 uses Semantic Versioning. There are three different kinds of releases related to the parts in the version number:
- X: If Kaidan introduces incompatible changes, you need to create a new major release.
- Y: If Kaidan introduces new functionality or refactoring, you need to create a new minor release.
- Z: If the latest release has some bugs, you can fix them, add the corresponding commits to the branch
Kaidan/X.Yand create a patch release including those fixes on top of the latest minor release.
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.