Project:KDE/Coding style

There are a number of rules and recommendations to follow when working on KDE-related packages. Following these will result in higher-quality ebuilds and reduce long-term maintenance burden. Not all items discussed are KDE-specific, but they often come up and are always good to remember.

General policies

 * Please ask a member before adding the KDE project to your package.


 * Don't commit major bumps of core packages (such as KDE Applications 18.08 -> 18.12) directly to the tree. Spending some time in the overlay first will reduce the number of issues hitting the main tree.


 * Avoid major changes to KDE ebuilds in the tree. They should go into the overlay first, applied to either master and/or stable ebuild branches as appropriate.


 * USE flag defaults should only be enabled for a good reason - such as it is commonly used, known to work and not pulling any dependencies. If in doubt, get a second opinion.


 * KDE-based applications should be in  5. Feel free to fix packages that don't follow this, and don't forget to make the appropriate slotmove entry.


 * Use the latest EAPI. Older EAPIs are banned in the overlay and repoman is happy to let you know.

Using eclasses
Packages hosted on kde.org that use extra-cmake-modules should inherit kde5 eclass, they follow a common directory structure, CMake macros and coding style for the eclass to work with. Packages from third-party repositories that do not follow the above mentioned structure should just inherit cmake-utils eclass instead.


 * Read the eclass reference for detailed information on features provided.


 * Don't forget to the appropriate phase function (such as kde5_src_prepare) when overriding.


 * Double check handbook support in your package - check, and similar for  files. To enable handbook support, set KDE_HANDBOOK="optional" (if possible) or KDE_HANDBOOK="forceoptional" (if necessary) or KDE_HANDBOOK="true".

Patches
We prefer to keep as close to upstream as possible, however there are a number of cases when we might want to carry a patch:
 * Distribution specific changes (such as supporting a slotted dependency).
 * Workarounds for bad bugs (to improve the user experience where an upstream fix is not yet available).
 * Backporting upstream fixes for bugs where we do not want to wait for the next release.

Most patches should go upstream. They can give feedback to improve the patch, everyone else will benefit, and we will reduce our maintenance burden. The preferred method is requesting review on Phabricator or GitLab.

Feel free to ask for assistance with the upstreaming process. A number of project members can also assist with committing and editing upstream bugs once the review has been approved.

Overlay

 * Always run repoman full on the ebuild subtree you're working on before committing anything.


 * Always use repoman commit when committing ebuilds. It will ensure your manifests are updated, and report any QA issues you might have forgotten about.


 * Packages in the overlay should be KDE-related in some way.


 * Try to keep one commit per change if possible. If more appropriate - one commit per feature.


 * All commit messages must look like this:

for example:


 * If you change ebuild names in kde-apps, synchronize those changes in the following locations if applicable and run regenerate-files:


 * Any changes made elsewhere will be lost in next regenerate-files tool run.

Bugzilla
There are a number of conventions used to help keep track of our bugs.


 * Watch out for bugs filed in the KDE component, as this bypasses bug wranglers and the package might have a different maintainer.
 * Bugs concerning the overlay should have their summary prefixed with [kde overlay].
 * Bugs that have fixes present in the overlay should be marked IN_PROGRESS, have the InOverlay keyword added, and kde overlay present in the whiteboard field.
 * It's useful to put fixed in  in the whiteboard field of bugs that were fixed by upstream

QA

 * Ensure that,   and   are always correctly separated. It may help to add   if needed.


 * Keep ebuilds clean, look at recommended ebuild formatting rules below (mandatory for kde-* categories). Use existing ebuilds (like kde-frameworks/kio) for reference.


 * Sort dependencies alphabetically - it makes it easier to manage them later


 * Put blocks at the begin of  section,   preferably before   - it's easier to spot them when they're in expected location.


 * Put optional dependencies after obligatory ones - again - improves readability.


 * Avoid single line expressions - they are utterly unreadable


 * Always indent dependencies with characters from new line (including other variable like   may be exception here) and always break line *after* dependency - it makes it easier to synchronize such deps semi-automatically between ebuilds using GUI diff/merge tools (less conflicts). The same applies to   as well.


 * Blockers added after upstream package changes or package splits should be maintained for 2 major versions. For example, we support a smooth upgrade from KDE Plasma 5.12 to 5.14, but not 5.12 to 5.15