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 herd to your package.


 * Don't commit bumps of core packages (such as KDE SC, CMake) 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 SC ebuilds in the tree. They should go into the overlay first, applied to either master and/or stable ebuild branches as appropriate.


 * Think about adding the debug USE flag to your package. It might not always be appropriate - it will have no effect on artwork or python-only packages, for example.


 * USE flag defaults (IUSE="+useflag") 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.


 * All KDE SC and miscellaneous KDE 4 applications should be in SLOT="4". 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
All KDE packages should inherit one of two eclasses. kde4-base is the most common, for applications with the main in the top level source directory. kde4-meta is used for applications that are part of a more complex source directory structure, such as repositories/tarballs that contain multiple applications.


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


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


 * Always check for linguas and add them to the KDE_LINGUAS variable.


 * 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="always".

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 bad bugs or where requested by users

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

Feel free to ask for assistance with the upstreaming process. A number of herd 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.


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


 * Do not use files, as we rely on the git commit log to track changes.


 * Include valid with all packages - not necessarily with  kde .


 * If you revbump some snapshots of yet-not-released packages (like phonon, soprano, eigen etc), always ensure it's visible *only* for those users that really need it and not for every ~arch users. For KDE dependencies, there are kdedeps-${SLOT} sets created for this purpose. regenerate-files tool will mask those ebuilds for everyone except those using kde-${SLOT} umask file helper, so those dependencies will be available only for them.


 * 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-base, 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 DEPEND and RDEPEND are always correctly separated. It may help to add COMMON_DEPEND if needed.


 * Keep ebuilds clean, look at recommended ebuild formatting rules below (obligatory for kde-base). Use existing ebuilds (like kdelibs) for reference.


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


 * Put blocks at the begin of RDEPEND section, !useflag?  preferably before useflag?  - 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 ${COMMONDEPEND} 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 PATCHES 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 4.5 to 4.7, but not 4.5 to 4.8