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.

KDE4 policies

 * NEVER EVER COMMIT NEW REVBUMPS NOR MAJOR CHANGES TO TREE DIRECTLY - ALWAYS USE overlay first so that more pairs of eyes can spot issues. Especially anything in kde-base.


 * Append valid - not necessarily with  kde  if you're proxy maintaining some ebuild. Never append  because file/folder history is determined by commit log.


 * NEVER EVER commit anything that can break metadata cache. Check every commit at least with repoman -v -d full!


 * Always separate DEPEND and RDEPEND properly (adding COMMON_DEPEND if needed).


 * Always use kde4-* eclasses. kde4-base for applications with main in toplevel source directory, kde4-meta for applications hidden deeper in source code directory structure and requiring common  from toplevel directory. See also KMEXTRA, KMEXTRACTONLY, KMCOMPILEONLY eclass variables. NEVER FORGET TO INVOKE kde4-{base,meta}_${phase_function} when overriding ebuild phase!


 * Always report CMake issues about everything directly to upstream and backport their fix.


 * Never use -j1 in ebuilds. Always report the issue upstream and wait for the resolution or fix yourself.


 * Double check handbook support in your package. For kde4-meta style ebuilds - look for or similar directory. Sometimes application handbooks are not trivial to assign (for example  ebuild), in such case ask Gentoo KDE team/HT members or contact upstream. To enable handbook support, set KDE_HANDBOOK=1 before inheriting kde eclasses.


 * Think about adding debug USE flag to your package. Do not add debug USE flag for artwork-only and python-only KDE packages. And don't forget to write entries for new local USE flags.


 * Do not enable USE flags by default (IUSE="+useflag") with no *good* reason. "Because I use it" is not enough. If uncertain - discuss it with the rest of the team. USE flags that are considered as commonly used, known to work and not pulling any dependencies, can be enabled by default right away.


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


 * Always fix automagic packages with macro_optional_ prefixing and report it upstream with patch.


 * Check your apps deps with dynlink-scanner in folder. Be aware, that this tool does not return complete runtime dependency chain, still it will find most automagic linking dependencies.


 * If you want our herd in the application and you are not Gentoo KDE team/HT member - ask us first.


 * All kde4 and kde-live misc applications should be in SLOT="4". Feel free to fix packages that don't follow this, and always add the correct blockers (be carefull not to block kde3 packages).


 * 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.

Block all versions of kdelibs <=4.1.80
 * Use the add_blocker function to add blocks. This ensures that the blocks are only added to RDEPEND. Some examples:

Block all versions of kdelibs <4.2.0

Block all versions of kde-menu (replaced by kdebase-menu)

Block all versions of kdelibs in KDE 4.1 or prior


 * For more details, read the comments in . Comment any new blockers you add.

Commiting

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


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

[] 
 * All commit messages must look like this:
 * Also append package version, when needed.


 * Some examples:

[kde-base/kdelibs-4.2.3] Synced with tree: fixed bug #333452, removed unnecessary solid patch, added debug to IUSE.

[kde-base/kdelibs-4.2.3] Moved to tree.


 * When you commit something related to existing bugzilla bug, add inOverlay to keywords to that bug, so that developers know about it. Also add [overlay-name] to bug summary.


 * if you refactor ebuild names in kde-base, *always* synchronize those changes in following locations if applicable:


 * Remember to do not edit autogenerated files, as your changes will be lost in next regenerate-files tool run.

QA

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

>=app-misc/strigi-0.6.3[dbus,qt4] dev-libs/libpcre dev-libs/libxml2
 * Sort dependencies alphabetically - it makes it easier to manage them later


 * Try to separate KEYWORDS and IUSE with some usually invariant variable (like LICENSE) - it makes it easier to merge changes between live and tagged ebuilds using GUI diff/merge tools. Always *avoid* merging/synchronizing ebuilds manually if possible - it's error prone. Use kompare  for it.


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

x11-proto/renderproto xinerama? ( x11-proto/xineramaproto )
 * Put optional dependencies after obligatory ones - again - improves readability.

ssl? ( dev-libs/openssl ) zeroconf? (
 * 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.