Warning, /network/kaidan/CONTRIBUTING.md is written in an unsupported language. File is not indexed.
0001 # Contributing 0002 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. 0005 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. 0008 0009 ## Branches 0010 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 0017 0018 ## Merge Requests (MR) 0019 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. 0023 0024 Please stick to the following steps for opening, reviewing and accepting MRs. 0025 0026 ### For Authors 0027 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. 0038 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. 0042 0043 ### For Reviewers 0044 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. 0052 0053 Reviews have to be done by at least one maintainer not involved as the MR's author or co-author. 0054 0055 ## Features 0056 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. 0058 0059 ## Configuration and Database Files 0060 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`. 0063 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) 0068 0069 ## Testing 0070 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`. 0075 0076 ## Styles 0077 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`. 0082 0083 ## Mobile Devices 0084 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. 0088 0089 ## Notifications 0090 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. 0095 0096 ## User Interface 0097 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). 0101 0102 ## Icons 0103 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). 0107 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`. 0111 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. 0115 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. 0118 0119 ## Builds and Dependencies 0120 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). 0127 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. 0134 0135 ## Releases 0136 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. 0139 0140 ## Translations 0141 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++. 0144 0145 ## Graphics 0146 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*. 0149 0150 ### Optimization 0151 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. 0153 0154 ### Copyright 0155 0156 The *LICENSE* file must be updated if there are copyright changes: 0157 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. 0161 0162 ### Logo 0163 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: 0166 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:email@example.com?join) by uploading a new avatar.