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

KDE-based applications should be in SLOT 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 should inherit kde.org eclass. Packages that use extra-cmake-modules should inherit ecm 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 eclass instead.

Read the eclass reference for detailed information on features provided.

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

Double check handbook support in your package - check doc/, doc/$PN and similar for .docbook files. To enable handbook support, set ECM_HANDBOOK="optional" (if possible) or ECM_HANDBOOK="forceoptional" (if necessary) or ECM_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:

CODE

<category/pn>: <summary of changes>

<Optional detailed description of changes>

for example:

CODE

kde-frameworks/extra-cmake-modules: drop dev-qt/qtcore RDEPEND
    
This was added in 83cadfedf9a2af7934f5456ab818c16ad5a1edf3 as certain modules
call qmake, but is now causing an unnecessary dependency as some consumers do
not use these modules and do not require qt at all.
    
Gentoo-bug: 572652

If you change ebuild names in kde-apps, synchronize those changes in the following locations if applicable and run regenerate-files:
- sets/
- Documentation/package.keywords/
- Documentation/package.unmask/

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 <version> in the whiteboard field of bugs that were fixed by upstream

QA

Ensure that BDEPEND, 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 (mandatory for kde-* categories). Use existing ebuilds (like kde-frameworks/kio) for reference.

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

CODE

>=app-crypt/gpgme-1.7.1[cxx,qt5]
dev-libs/libpcre
dev-libs/libxml2

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

CODE

RDEPEND="${DEPEND}
	!sddm? ( x11-misc/lightdm )
"

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

CODE

x11-libs/libxcb
wayland? ( $(add_frameworks_dep kwayland) )

Avoid single line expressions - they are utterly unreadable

CODE

bzip2? ( app-arch/bzip2 )
ssl? (
	gnutls? ( net-libs/gnutls )
	!gnutls? (
		!libressl? ( dev-libs/openssl:0= )
		libressl? ( dev-libs/libressl:0= )
	)
)

Always indent dependencies with tab characters from new line (including other variable like ${DEPEND} 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.

CODE

BDEPEND="
	doc? ( app-doc/doxygen )
"
DEPEND="
	dev-libs/libgcrypt:0=
	virtual/pam
"
# sth? ( dev/foo ) - re-add when in tree
RDEPEND="${DEPEND}
	net-misc/socat
"

PATCHES=(
	"${FILESDIR}/${PN}-5.14.80-startkde-script.patch"
	"${FILESDIR}/${PN}-5.10-startplasmacompositor-script.patch"
	"${FILESDIR}/${PN}-5.12.80-tests-optional.patch"
)

CODE

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE pkgmetadata SYSTEM "http://www.gentoo.org/dtd/metadata.dtd">
<pkgmetadata>
    <maintainer type="project">
        <email>kde@gentoo.org</email>
        <name>Gentoo KDE Project</name>
    </maintainer>
</pkgmetadata>

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.15 to 5.17, but not 5.15 to 5.18