Warning, /network/kaidan/CONTRIBUTING.md is written in an unsupported language. File is not indexed.

0001 # Contributing
0003 This is a guideline for contributing to Kaidan.
0004 There is also a guide for a [basic setup](https://invent.kde.org/network/kaidan/-/wikis/setup) targeted at contributors which are unfamiliar with KDE Identity, GitLab or Git and want to start contributing quickly.
0006 In order to contribute to Kaidan, please create branches on your forked repository and submit merge requests for them.
0007 Please do not create branches on Kaidan's main repository or push your commits directly to its *master* branch.
0009 ## Branches
0011 Use the following prefixes for branch names:
0012 * `feature/` for new features (changes with new behavior)
0013 * `refactor/` for changes of the code structure without changing the general behavior
0014 * `fix/` for fixes (changes for intended / correct behavior)
0015 * `design/` for design changes
0016 * `doc/` for documentation
0018 ## Merge Requests (MR)
0020 Currently, Linus Jahn (@lnj) and Jonah BrĂ¼chert (@jbbgameich) are the maintainers of Kaidan.
0021 They are responsible for accepting MRs.
0022 Nevertheless, everybody is welcome to review MRs and give feedback on them.
0024 Please stick to the following steps for opening, reviewing and accepting MRs.
0026 ### For Authors
0028 1. Create a new branch from the *master* branch to work on it.
0029 1. Write short commit messages starting with an upper case letter and the imperative.
0030 1. Split your commits logically.
0031 1. Do not mix unrelated changes in the same MR.
0032 1. Create an MR with the *master* branch as its target.
0033 1. 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.
0034 1. A maintainer and possibly other reviewers will give you feedback.
0035 1. Improve your MR according to their feedback, push your commits and close open threads via the *Resolve thread* button.
0036 1. If necessary, modify, reorder or squash your commits and force-push (`git push -f`) the result to the MR's branch.
0037 1. As soon as all threads on your MR are resolved, a maintainer will merge your commits into the *master* branch.
0039 Please do not merge your commits into the *master* branch by yourself.
0040 If maintainers approved your MR but have not yet merged it, that probably means that they are waiting for the approval of additional maintainers.
0041 Feel free to ask if anything is unclear.
0043 ### For Reviewers
0045 1. Provide detailed descriptions of found issues to the author.
0046 1. Try to give the author concrete proposals for improving the code via the *Insert suggestion* button while commenting.
0047 1. 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.
0048 1. In case you are a maintainer:
0049         1. If you think that no additional review is needed, make editorial modifications (such as squashing the commits) and merge the result directly.
0050         1. 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.
0051 1. 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.
0053 Reviews have to be done by at least one maintainer not involved as the MR's author or co-author.
0055 ## Features
0057 If you add or update a functionality specified by an [XMPP Extension Protocol (XEP)](https://xmpp.org/extensions/), adjust the [Description of a Project (DOAP) file](/misc/doap.xml) accordingly.
0059 ## Configuration and Database Files
0061 Kaidan uses a configuration file to store settings such as the last window size.
0062 On Linux, that configuration file is located at `.config/kaidan/kaidan.conf`.
0064 Kaidan's database is an SQLite file.
0065 It stores, for example, contacts and messages.
0066 On Linux, you can find it at `.local/kaidan/kaidan.sqlite3`.
0067 To open it, you need an SQLite application (e.g., `sqlitebrowser`, use `sudo apt install sqlitebrowser` to install it on Debian-based systems)
0069 ## Testing
0071 The environment variable `KAIDAN_PROFILE` can be set to run Kaidan with custom configuration and database files.
0072 It defines their filename suffixes after a separating `-` while their file extensions cannot be changed.
0073 In combination with the command-line option `--multiple`, multiple instances of Kaidan can be run simultaneously with different profiles.
0074 E.g., if you set `KAIDAN_PROFILE=test`, the configuration file will be `kaidan-test.conf` and the database file `messages-test.sqlite3`.
0076 ## Styles
0078 A style influences Kaidan's look.
0079 It can be set via the environment variable `QT_QUICK_CONTROLS_STYLE`.
0080 Kaidan's default style is `org.kde.desktop`.
0081 You can run Kaidan using Android's `Material` style with `QT_QUICK_CONTROLS_STYLE=Material kaidan`.
0083 ## Mobile Devices
0085 Kaidan can be run on desktop devices as well as on mobile devices with touchscreens.
0086 A user interface optimized for mobile devices can be applied via the environment variable `QT_QUICK_CONTROLS_MOBILE`.
0087 You can run Kaidan with `QT_QUICK_CONTROLS_MOBILE=true kaidan` in order to get its mobile view.
0089 ## Notifications
0091 Notifications are triggered by `src/Notifications` via [KNotifications](https://api.kde.org/frameworks/knotifications/html/index.html).
0092 The configuration file `misc/kaidan.notifyrc` is used by KNotifications.
0093 It is automatically installed when you install Kaidan.
0094 Remember to install Kaidan again if you modified that file in order to see any changes.
0096 ## User Interface
0098 Kaidan depends on the user interface framework [Kirigami](https://api.kde.org/frameworks/kirigami/html/index.html).
0099 Please use its visual components within Kaidan instead of creating own ones as far as it makes sense.
0100 You can have a look at the components Kirigami provides by opening the [Kirigami Gallery](https://invent.kde.org/sdk/kirigami-gallery) (use `sudo apt install kirigami-gallery` to install it and `kirigami2gallery` to run it on Debian-based systems).
0102 ## Icons
0104 For using an icon as a user interface element such as [`Kirigami.Icon`](https://api.kde.org/frameworks/kirigami/html/classIcon.html) or [`QtQuick.Controls.Button`](https://doc.qt.io/qt-5/qml-qtquick-controls2-button.html), you need to set the actual icon as its [`source`](https://api.kde.org/frameworks/kirigami/html/classIcon.html#ab04bfe8d23fdd9779421aadaaaa022f4) resp. [`name`](https://doc.qt.io/qt-5/qml-qtquick-controls2-abstractbutton.html#icon.name-prop) property.
0105 All icons used by Kaidan must be referenced in [`kirigami-icons.qrc`](https://invent.kde.org/melvo/kaidan/-/blob/master/kirigami-icons.qrc).
0106 Kaidan's default icon theme is [Breeze](https://invent.kde.org/frameworks/breeze-icons).
0108 Instead of using new icons, search and use icons that are already used for similar purposes.
0109 If your purpose needs a new icon that is not yet used by Kaidan, you can find one with [Cuttlefish](https://invent.kde.org/plasma/plasma-sdk/-/tree/master/cuttlefish) (use `sudo apt install plasma-sdk` to install it and `cuttlefish` to run it on Debian-based systems).
0110 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 `kirigami-icons.qrc`.
0112 Always make sure that you use the right path within [Breeze's icon directory](https://invent.kde.org/frameworks/breeze-icons/-/tree/master/icons).
0113 Cuttlefish will open the chosen icon of your system's theme.
0114 If that is not Breeze, you need to find the corresponding icon in Breeze's icon directory and use that path.
0116 The system Kaidan is run on can apply a different icon theme than Kaidan's default.
0117 For good compatibility with various icon themes, it is often better to use the `-symbolic.svg` variant of an icon.
0119 ## Builds and Dependencies
0121 On a daily basis, Kaidan is automatically built for various systems.
0122 Those *nightly builds* are based on Kaidan's *master* branch.
0123 Kaidan is packaged for several [Linux distributions](https://repology.org/project/kaidan/versions).
0124 For distributions supporting Flatpak, there is a [Flatpak configuration](https://invent.kde.org/packaging/flatpak-kde-applications/-/blob/master/im.kaidan.kaidan.json) (called [*manifest*](https://docs.flatpak.org/en/latest/manifests.html)) for [nightly builds](https://invent.kde.org/network/kaidan/-/wikis/using/flatpak).
0125 There is also a [Flatpak configuration](https://github.com/flathub/im.kaidan.kaidan/blob/master/im.kaidan.kaidan.json) for [stable builds on Flathub](https://flathub.org/apps/details/im.kaidan.kaidan).
0126 In addition, there is a [KDE Craft configuration](https://invent.kde.org/packaging/craft-blueprints-kde/-/blob/master/kde/unreleased/kaidan/kaidan.py) (called [*blueprint*](https://community.kde.org/Craft/Blueprints)) for [Windows, macOS and Android builds](https://binary-factory.kde.org/search/?q=kaidan).
0128 Dependencies are mainly managed by Kaidan's [CMakeLists](/CMakeLists.txt) file.
0129 When you add or remove dependencies, update the [README](/README.md#dependencies) and the [building guides](https://invent.kde.org/network/kaidan/-/wikis/home#building-kaidan-from-sources) as well.
0130 You also need to modify the KDE Craft and Flatpak configuration files for Kaidan.
0131 It is sometimes needed to update the KDE Craft configurations for [QXmpp](https://invent.kde.org/packaging/craft-blueprints-kde/-/blob/master/qt-libs/qxmpp/qxmpp.py), [libomemo-c](https://invent.kde.org/packaging/craft-blueprints-kde/-/blob/master/libs/libomemo-c/libomemo-c.py) and [zxing-cpp](https://invent.kde.org/packaging/craft-blueprints-kde/-/blob/master/libs/zxing-cpp/zxing-cpp.py) as well.
0132 That way, Kaidan can be built correctly by KDE's automated process.
0133 As soon as the configuration files are updated and Kaidan is automatically built, the corresponding files can be downloaded.
0135 ## Releases
0137 Kaidan's releases are marked by [tags](https://invent.kde.org/network/kaidan/-/tags).
0138 For each release, its source code and the source code's signature is [uploaded](https://download.kde.org/unstable/kaidan/) by one of Kaidan's maintainers.
0140 ## Translations
0142 Kaidan is translated via [KDE Localization](https://l10n.kde.org/stats/gui/trunk-kf5/package/kaidan/).
0143 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 `QString`s in C++.
0145 ## Graphics
0147 The preferred format for graphics in Kaidan is *SVG*.
0148 If SVG is not applicable like for screenshots, the graphic should have the format *PNG*.
0150 ### Optimization
0152 In any case, the new or modified graphic must be [optimized](https://invent.kde.org/network/kaidan/-/wikis/optimizing-graphics) before adding it to a commit.
0154 ### Copyright
0156 The *LICENSE* file must be updated if there are copyright changes:
0158 1. Add to *utils/generate-license.py* a new `CopyrightTarget` for a new graphic or change an existing one for a modification of an existing graphic.
0159 1. Execute `utils/generate-license.py > LICENSE` for updating the *LICENSE* file.
0160 1. Add those two file changes to the same commit which contains the new or modified graphic.
0162 ### Logo
0164 If the logo is changed, it has to be done in a separate commit.
0165 Furthermore, the logo has to be updated on multiple other places:
0167 1. For this GitLab project by creating a [sysadmin request](https://go.kde.org/systickets) and providing a link to a PNG version in its description.
0168 1. In the [repository of Kaidan's website](https://invent.kde.org/websites/kaidan-im) by updating all instances of `favicon*` and `logo*`.
0169 1. On [Kaidan's Mastodon profile](https://fosstodon.org/@kaidan) by uploading a new avatar.
0170 1. In [Kaidan's support chat](xmpp:kaidan@muc.kaidan.im?join) by uploading a new avatar.