Difference between revisions of "Get Involved/development"

Jump to: navigation, search
(Mentor program)
(Add openSUSE errata section)
 
(151 intermediate revisions by 42 users not shown)
Line 1: Line 1:
__NOTOC__
+
[[File:Konqui dev close cropped.png|right|x200px|]]
== Becoming a KDE Developer ==
+
By joining the ranks of KDE developers, you will get to implement new features and defeat bugs both daunting and simple, all while collaborating to make coherent and stable releases. Developers collaborate in teams based on what area they are working in. These can be small teams working on a single application, up to large teams working on a group of related pieces of software. Many developers are in more than one team.
  
[[Image:development.png|Development|left]]By joining the ranks of KDE developers, you will get to implement new features and defeat daunting bugs, all while collaborating to make coherent and stable releases. Developers collaborate in teams based on what area they are working in, such as [http://edu.kde.org/ Education], [http://pim.kde.org/ Productivity], or [http://games.kde.org/ Games].
+
KDE runs or participates in several mentoring programs to help new developers, including an informal list of people who are willing to help newcomers get started. See the [[Mentoring]] page for more details.
  
Frank Osterfeld advises "start small and scratch your own itch, at least that's what kept me motivated in the beginning."
+
{{Info|While any operating system can be used to patch or develop KDE software, it's easiest if you use a Linux distribution that provides relatively recent versions of Qt and KDE Frameworks, such as Arch/Manjaro, Fedora, KDE Neon, openSUSE Tumbleweed, or non-LTS versions of Ubuntu.<br /><br />Support for distros that ship older software (such as Debian, Ubuntu/Kubuntu 18.04, and openSUSE Leap 15) is still experimental and you may have a better experience developing with one of the distributions mentioned above in a virtual machine.}}
  
As a result of a [http://dot.kde.org/2012/02/05/kde-development-%E2%80%93-beginners-guide/ Sprint] held in October 2011 we now have a [http://flossmanuals.net/kde-guide/ Beginner's Guide to KDE Development] available to ease the new contributors way into KDE development.
 
  
== Communicating with the team ==
 
  
There are many ways to get in touch with KDE developers, and developers for a specific project:<br /> Start at [irc://irc.kde.org/kde-devel <nowiki>#kde-devel</nowiki>] on irc.freenode.net, or [http://kde.org/support/#irc learn more about IRC].<br /> The central mailinglist for development is the [https://mail.kde.org/mailman/listinfo/kde-devel kde-devel mailing list], [http://kde.org/support/#mailinglists learn about mailing lists]. However each team has its own messaging channels, both on IRC and on the mailinglists, you can find a list [http://www.kde.org/mailinglists/ here].
+
== New to C++/Qt software development? ==
 +
Most KDE software is written in C++ using the [https://www.qt.io Qt toolkit] and [[Frameworks | KDE Frameworks]]. Though prior experience with these technologies or other programming languages is helpful, you don't need to be a C++ programmer to get started! For example, no programming knowledge whatsoever is required to do things like improve text labels.
  
== Getting and building the code ==
+
If you'd like to dive deeper, the Qt wiki contains [https://wiki.qt.io/Books a list of online books] for learning Qt programming. Qt also provides [http://doc.qt.io/qt-5/qtexamplesandtutorials.html lots of examples] you can look at. Information about KDE Frameworks can be found on the [https://techbase.kde.org TechBase wiki], and a [[Books | book]] is available.
  
In most cases, you will want to download, compile and install KDE trunk (our development tree) to start developing. Read the [http://techbase.kde.org/Getting_Started/Build/Unstable_Version unstable building guide]. If you get stuck or get errors, that's OK. You might not need to compile the whole set of applications, but getting started is a good step.
 
  
== Platform and Documentation ==
 
  
KDE is written in C++ and uses the Qt framework. If you've never used Qt before, that's not a problem. Before you get started, you'll want to brush up on C++/Qt and our coding guidelines:
+
== One-time setup: your development environment ==
 +
To build software, you need a '''development environment''': a set of tools that allows you to access and edit the source code, compile it into a form that the computer can run, and deploy it to a safe location. We will now go through the process of setting one up. To accomplish these tasks, you will need to enter commands using a terminal program, such as KDE's Konsole (but any terminal program will suffice).
  
* [http://www.parashift.com/c++-faq-lite/ C++ FAQ lite] - at some point, you'll have a question that is answered here.
+
If you're not familiar with the command line interface, you can [https://lifehacker.com/5633909/who-needs-a-mouse-learn-to-use-the-command-line-for-almost-anything find a reasonable tutorial here]. However advanced command-line skills are not required, and you will learn what you need along the way!
* [http://original.jamesthornton.com/eckel/TICPP-2nd-ed-Vol-one/Frames.html Thinking in C++ (volume 1)], [http://original.jamesthornton.com/eckel/TICPP-2nd-ed-Vol-two/Frames.html Thinking in C++ (volume 2)] - an online book that goes into some of the technical details of C++
 
* [http://www.beginning-kdevelop-programming.co.uk/ Beginning KDevelop Programming] - a great guide from start to finish
 
* [http://doc.trolltech.com/4.7/all-examples.html Qt Examples] - If you're doing any serious coding in KDE you will need to understand Qt. These examples explain what's up but it will take a couple hours. You can do that later.
 
* [http://techbase.kde.org/Development/Tutorials Basic KDE development tutorials]
 
* [http://techbase.kde.org/Development KDE coding HOWTO's] - good coding documentation for beginners
 
* [http://techbase.kde.org/Contribute/Send_Patches Patches HOWTO] - until you earn an account in SVN, your contributions will be made as patches
 
* [http://techbase.kde.org/Schedules The KDE Development Plans] - This is the bigger picture for the development efforts of the KDE project, everyone should understand these before going forward
 
* [http://en.flossmanuals.net/kde-guide/ The definite KDE dev book] - a comprehensive guide for KDE developers to be.
 
  
== Tasks ==
+
{{Note|'''Everything in this section only needs to be done once.''' Once you've done it, your development environment is set up and you can use it to submit patches and develop KDE Software!}}
  
Now you have the code on your computer and maybe got some of it to compile. Here are some tasks for you to get started. You can get your first contribution committed into the project within 1 hour!
 
  
* [http://techbase.kde.org/Contribute/Bugsquad/Howto The Bugs Howto] - explains how to use and triage bugs. Why's it useful? It makes bug hunting and fixing easier for developers, so more bugs get fixed. Why choose bug triage instead of ...? It doesn't take much time to look over a bug, so it comes in nice small chunks. What skills do I need to do it? Not much, just a bit of patience and sometimes some perseverance. (quote from [http://accentgrave.blogspot.com/2006/03/ive-got-little-bit-of-free-time-so.html Phil's Triage Guide])
+
=== Install basic tools ===
* [http://www.englishbreakfastnetwork.org/ English Breakfast Network] - provides a list of functions that need to be documented. Try one of these for practice with svn and doxygen.
+
First you will need to use your operating system's package manager to install some basic tools:
* [http://wiki.koffice.org/index.php?title=Junior_Jobs KOffice Junior Jobs] - simple programming jobs for KOffice
+
* Arch/Manjaro: <code>sudo pacman -S git cmake dialog</code>
* [https://bugs.kde.org/buglist.cgi?keywords=junior-jobs&bug_status=UNCONFIRMED&bug_status=NEW&bug_status=ASSIGNED&bug_status=REOPENED&cmdtype=doit Junior Jobs on bugzilla] - a place where people mark jobs that might be easy for beginners to fix
+
* Fedora: <code>sudo dnf install git cmake dialog perl</code>
* [https://bugs.kde.org/ KDE Bugzilla] - keeps track of all the bugs in KDE, you will want to bash them all
+
* KDE Neon/Kubuntu/Ubuntu/Debian: <code>sudo apt install git cmake dialog</code>
 +
* openSUSE Leap & Tumbleweed: <code>sudo zypper install git cmake dialog</code>
 +
<br />
  
== Mentor program ==
 
  
Getting started in a big project can be hard. Here are some people that are willing to help you learn the ropes and get you on board:
+
=== Configure Git ===
 +
We need to set your authorship information properly so that any changes you make can be properly attributed to you:
 +
{{Input|1=<nowiki>
 +
git config --global user.name "Your Name"
 +
git config --global user.email "you@email.com"
 +
</nowiki>}}
  
* Blake Mordegarius (<span class="mailme"> mordegarius at gmail dot com</span>)<br />
+
{{Note|The name you provide should be your actual name, not your KDE Identity username.
* Trever Fischer (<span class="mailme"> tdfischer at fedoraproject dot org </span>)<br /> Developer on the Phonon project
+
<nowiki>
* Eike Hein (<span class="mailme">hein at kde dot org</span>)<br /> application developer; Konversation maintainer
 
* Albert Astals Cid (<span class="mailme">aacid at kde dot org</span>)<br /> available to hand out junior tasks
 
* Peter Simonsson (<span class="mailme">peter dot simonsson at gmail dot com</span>)<br /> application developer; KOffice devel/Kivio maintainer
 
* Will Entriken (<span class="mailme">kde dot org at phor dot net</span>)<br /> Google Summer of Code KDE developer
 
* Anne-Marie Mahfouf (<span class="mailme">annemarie dot mahfouf at free dot fr</span>)<br /> KDE-Edu development, KDE4 development, and tutorial writing
 
* Jeremy Whiting (<span class="mailme">jpwhiting at kde dot org</span>)<br /> Developer
 
* Teo Mrnjavac (<span class="mailme">teo at kde dot org</span>)<br /> Developer, Amarok
 
* Your name here!<br /> Volunteer to be a mentor -&gt; <span class="mailme">kde dot org at phor dot net</span>
 
<!-- BUMP YOURSELF WHENEVER YOU WANT! -->
 
  
If you are a student you might be interested in the Google Summer of Code program. KDE has been a mentoring organization for many years, we have a separate wiki page  with information on participating in [[GSoC|Google Summer of Code with KDE]].
+
</nowiki>
 +
The email address you specify above must be the same as the email address used for your https://bugs.kde.org account. If they don't match, then the <tt>BUG: </tt> and <tt>FEATURE: </tt> keywords won't work (see [https://techbase.kde.org/Development/Git/Configuration#Basic_Settings this page] for more information).}}
 +
<br />
 +
 
 +
=== Set up kdesrc-build ===
 +
Next, we need a method of '''managing dependencies'''. Every software has dependencies: other pieces of software that provide the functionality they rely on. In order to compile any piece of software, its dependencies must be available.
 +
 
 +
Most Linux-based operating systems do not provide development packages that are up-to-date enough for working on KDE software, so we will compile all the KDE dependencies ourselves. To do this, we use a command-line tool called <code>kdesrc-build</code> to download, manage, and build KDE source code repositories. Let's set it up now! First, we create a new directory for all the KDE source code we will be using. We then clone the source code repository that holds <code>kdesrc-build</code> in that directory, so we have a local copy of it on our computer.
 +
 
 +
{{Input|1=<nowiki>
 +
mkdir -p ~/kde/src
 +
cd ~/kde/src/
 +
git clone https://anongit.kde.org/kdesrc-build.git  && cd kdesrc-build
 +
</nowiki>}}
 +
 
 +
Next, it's time to set up <code>kdesrc-build</code> and pick up the changes it made to your <tt>~/.bashrc</tt> for the current terminal session:
 +
 
 +
{{Input|1=<nowiki>
 +
./kdesrc-build --initial-setup
 +
source ~/.bashrc
 +
</nowiki>}}
 +
 
 +
{{Warning|Do not quote or escape any file paths entered in the wizard! And do not run the command <code>kdesrc-build</code> by itself without any arguments because this will build everything, which is probably overkill right now.}}
 +
 
 +
The initial setup tries to install the basic packages for compiling Qt and KDE software on your distro. It also creates a <code>~/.kdesrc-buildrc</code> configuration file.
 +
If you want a more guided setup process for <code>kdesrc-build</code>, run the command <code>kdesrc-build-setup</code> instead. However, unlike <code>--initial-setup</code>, it won't install packages from your distro for compiling programs so you will have to do that yourself.
 +
 
 +
Consult the [https://docs.kde.org/trunk5/en/extragear-utils//kdesrc-build/ kdesrc-build manual] for more information and options.
 +
 
 +
=== Set up Qt ===
 +
By default, <code>kdesrc-build</code> will build from source all the dependencies that a program or framework needs, including the Qt toolkit itself, because the <code>include-dependencies</code> option is set as default in the <code>~/.kdesrc-buildrc</code> file.
 +
 
 +
If your Linux distribution provides a recent version of Qt (5.11 or newer), you can save some time and disk space and use that version instead of building your own. To configure <code>kdesrc-build</code> to skip building Qt, open the configuration file <code>~/.kdesrc-buildrc</code> and comment out the <code>qtdir</code> and two <code>include</code> lines related to qt5.
 +
 
 +
 
 +
=== Download non-KDE dependencies ===
 +
Even though <code>kdesrc-build</code> will take care of the KDE dependencies for you, it does not yet have the ability to install non-KDE dependencies (see https://bugs.kde.org/show_bug.cgi?id=402428), which are typically acquired using your package manager. To install the required non-KDE dependencies, [[Guidelines and HOWTOs/Build from source/Install the dependencies|read this page]] and follow the instructions laid out there.
 +
 
 +
Once that's done, your development environment is set up and ready to build software! Let's take it for a spin.
 +
 
 +
 
 +
 
 +
== Build some software ==
 +
It can take an hour or more to compile a KDE Application, Framework, or Plasma itself for the first time. The reason for this is that <code>kdesrc-build</code> is compiling ''all'' of the KDE dependencies (See https://invent.kde.org/kde/kdesrc-build/issues/17). The next time you want to compile that or any other piece of KDE software, it will be much faster since most of the dependencies will have already been compiled. If you don't want to build all dependencies (e.g., because you are using a rolling release distro that provides recent versions of software), edit the same configuration file and simply set <code>include-dependencies</code> to '''false''' or add the <code>--no-include-dependencies</code> option when running <code>kdesrc-build</code>.
 +
 
 +
 
 +
=== Applications ===
 +
'''[[KDE Applications]]''' like Dolphin, Okular, Konsole and Gwenview are standalone apps that can be run on multiple platforms, such as Plasma, GNOME, even macOS and Windows! New versions of KDE Applications are [[Schedules/Applications/18.12 Release Schedule|released three times a year]]. Note that the Discover app store (git repo name: <tt>plasma-discover</tt>) and System Settings app (git repo name: <tt>systemsettings</tt>) are distributed alongside Plasma, but they build like apps using the below instructions. A list of all KDE applications can be found here: https://userbase.kde.org/Applications.
 +
 
 +
For example, here is how to build Dolphin, the KDE file manager:
 +
 
 +
{{Input|1=<nowiki>
 +
kdesrc-build dolphin
 +
</nowiki>}}
 +
 
 +
As a part of this process, Dolphin was installed to <tt>~/kde/usr/bin/dolphin</tt>. '''There is no need to manually install anything;''' <tt>kdesrc-build</tt> installed it for you! <tt>Source</tt> the project's auto-generated <tt>prefix.sh</tt> file every time you want to run your custom-compiled version of Dolphin:
 +
 
 +
{{Input|1=<nowiki>
 +
source ~/kde/build/dolphin/prefix.sh
 +
~/kde/usr/bin/dolphin
 +
</nowiki>}}
 +
 
 +
Did it run? If so, then '''congratulations, you just compiled your own version of Dolphin from source code!'''
 +
 
 +
 
 +
=== Frameworks ===
 +
'''[[Frameworks|KDE Frameworks]]''' are libraries of tools and features that can be used by any application or Plasma itself. New versions of KDE Frameworks are [[Schedules/Frameworks|released once a month]]. A list of all frameworks can be found here: https://api.kde.org/frameworks/index.html.
 +
 
 +
For example, here is how to build the KIO framework:
 +
 
 +
{{Input|1=<nowiki>
 +
kdesrc-build kio
 +
</nowiki>}}
 +
 
 +
Now you can run an existing app using your custom-made version of the framework! For example, the following will run Dolphin, but it will be using the KIO library that you just built:
 +
 
 +
{{Input|1=<nowiki>
 +
source ~/kde/build/kio/prefix.sh
 +
~/kde/usr/bin/dolphin
 +
</nowiki>}}
 +
 
 +
 
 +
=== Plasma ===
 +
'''[[Plasma|KDE Plasma]]''' is the environment in which you can run apps. Plasma is responsible for providing a desktop with wallpaper, app launchers, and widgets; displaying notifications; managing wired and wireless networks; and similar operating-system level tasks. New versions of Plasma are [[Schedules/Plasma 5|released three times a year]].
 +
 
 +
Here is how to build the Plasma desktop environment, including its window manager and its built-in apps:
 +
 
 +
{{Input|1=<nowiki>
 +
kdesrc-build plasma-desktop plasma-workspace plasma-framework plasma-nm plasma-pa plasma-thunderbolt plasma-vault plasma-workspace-wallpapers kdeplasma-addons kwin systemsettings kscreen breeze discover kinfocenter --include-dependencies
 +
</nowiki>}}
 +
 
 +
To run your custom-built Plasma, first make it accessible from the SDDM login screen by running the following command:
 +
{{Input|1=<nowiki>
 +
~/kde/build/plasma-workspace/login-sessions/install-sessions.sh
 +
</nowiki>}}
 +
 
 +
If you don't have a plasma system you also need to edit the dbus session dir.
 +
create a file named kde-dev.conf in /usr/share/dbus-1/session.d and paste this
 +
 
 +
    <busconfig>
 +
        <servicedir>/kde install dir/share/dbus-1/services</servicedir>
 +
    </busconfig>
 +
 
 +
After that, you can log out and select your new plasma session in SDDM's session chooser menu (which is located in the bottom-left corner of the screen if you're using the Breeze SDDM theme).
 +
 
 +
=== How to solve build problems ===
 +
Did one or more modules fail to build (displayed in red font) using <code>kdesrc-build</code>? Here's what to do:
 +
 
 +
# Try building the failing module again from scratch using <code>kdesrc-build [failing module] --refresh-build</code>
 +
# Make sure that you have all the dependencies for the failing module. Go back to the [[#Download non-KDE dependencies]] section and re-install the non-KDE dependencies. If that doesn't fix the problem. Open the log file for the failing module, which <code>kdesrc-build</code> will print the path at the end of its output. Scroll to the bottom of the log file and read the output to see what missing dependency it is complaining about, then find and install the corresponding package using your distro's package manager your distro. If several looks relevant, install them all just to be safe.
 +
# Check the [https://build.kde.org/view/Failing/ list of currently broken modules] on the KDE build server. If it's broken there, then it's not your fault. :)
 +
# Ask for help in the the [https://webchat.kde.org/#/room/#kde-devel:kde.org #kde-devel] channel on [[Matrix]] or freenode [[Internet Relay Chat | IRC]]. See [[Get Involved/development#Communicate with the team]]
 +
 
 +
 
 +
== Choose what to do ==
 +
Now that you can compile and deploy custom versions of KDE software, you can open your editor and start hacking on the source code! The code for the version of Dolphin that you built earlier is located at <tt>~/kde/src/dolphin/</tt>; other projects you build with <code>kdesrc-build</code> will live in similar locations.
 +
 
 +
A good place to start is with a small bug or feature in an existing piece of software that affects you personally ("scratch your own itch"). Get in touch with the existing developers (see [[#Communicate with the team|Communicate with the team]], below) and they can help you out, by pointing you to the right place in the code and giving advice about how to tackle the problem.
 +
 
 +
Try not to start by proposing or working on major features or significant design changes. These can be controversial, and the smoothest way to get going is by working on relatively non-controversial bugfixes. Start slowly and build trust!
 +
 
 +
Here are some other ideas for starting points:
 +
 
 +
* Improve awkwardly-worded messages and labels that are written in English. This is a great way for non-programmers to contribute! If you can compile software and have a good grasp of English, you can make a big difference here.
 +
* Work on [https://bugs.kde.org/buglist.cgi?bug_status=UNCONFIRMED&bug_status=CONFIRMED&bug_status=NEW&bug_status=ASSIGNED&bug_status=REOPENED&keywords=junior-jobs&list_id=1340815 Junior Jobs], which are small tasks that are suitable for beginners (both bugs and features).
 +
* Work on [https://bugs.kde.org/buglist.cgi?bug_status=UNCONFIRMED&bug_status=CONFIRMED&bug_status=ASSIGNED&bug_status=REOPENED&keywords=usability&keywords_type=allwords&list_id=1493316&order=product%2Cchangeddate%20DESC%2Cbug_status%20DESC%2Cresolution%2Cpriority%2Cassigned_to%2Cbug_id&query_format=advanced Bugs related to] KDE's [[Goals/Usability_%26_Productivity | Usability & Productivity initiative]], many of which are small and easy.
 +
* [http://www.englishbreakfastnetwork.org/ The English Breakfast Network] searches out simple, common issues in code that should be fixed, and going through the problems on there can provide a good overview of the code.
 +
 
 +
 
 +
 
 +
== Test your changes ==
 +
Once you've made some changes, make sure the project still compiles and installs, and make sure the changes have the desired effect when you run the software. Then it's time to run the project's unit tests:
 +
 
 +
{{Input|1=<nowiki>
 +
cd ~/kde/build/dolphin/
 +
source ./prefix.sh
 +
ctest --output-on-failure
 +
</nowiki>}}
 +
 
 +
If any test fails, that needs to be investigated and fixed before you can proceed. Once the tests pass, then run the software again to make sure it still behaves properly. If it doesn't, then go back and work on your patch some more, then re-compile and re-deploy, and test again, until the program does what you'd like it to do and all tests pass.
 +
 
 +
 
 +
 
 +
== Submit a patch ==
 +
Once you're happy with your patch and have verified that it does what you want, it's time to '''generate a diff.''' A diff is a textual representation of the differences between original versions of the files you changed, and the new ones you've produced. You can generate a diff by entering the source repository and running <code>git diff</code>, but we recommend using the <code>arc</code> tool, which will generate a diff and submit it for review very quickly and easily! You can learn how to set it up [https://community.kde.org/Infrastructure/Phabricator#Using_Arcanist_to_post_patches here].
 +
 
 +
KDE uses [https://phabricator.kde.org Phabricator] for patch submission and review. [[Infrastructure/Phabricator|Learn more about how to submit a patch with Phabricator]].
 +
 
 +
 
 +
 
 +
== Communicate with the team ==
 +
There are several ways to get in touch with KDE developers, either generally or for a specific project. The most important communications channels are:
 +
* The [https://webchat.kde.org/#/room/#kde-devel:kde.org #kde-devel] channel on [[Matrix]] or the freenode [[Internet Relay Chat | IRC]], which is where KDE developers chat in real time about their work.
 +
* The [https://mail.kde.org/mailman/listinfo/kde-devel kde-devel mailing list] is the primary development mailing list. [http://kde.org/support/#mailinglists Learn more about mailing lists].
 +
 
 +
These are general KDE development communication channels, and you may get directed to a more appropriate place for the project you are interested in. There is a [http://www.kde.org/mailinglists/ list of mailing lists] if you want to find a mailing list for a specific team directly. Many teams have their own real-time chat channels, too.
 +
 
 +
You can also try looking for the team's section on the [[Main Page]] of this wiki. Many teams have information there for new contributors.
 +
 
 +
 
 +
 
 +
== Next steps ==
 +
Sharpen your skills by going through the [https://techbase.kde.org/Development/Tutorials KDE development tutorials]. And try out [http://www.kdevelop.org KDevelop], the KDE IDE.
 +
 
 +
After you have had several drama-free patches accepted, a KDE developer is likely to suggest you get a [[Infrastructure/Get a Developer Account|Developer account]], which will allow you to commit directly to KDE projects. With very few limits on where you can commit, you will be expected to act responsibly. At this point, congratulations! You are officially a KDE developer!
 +
 
 +
You may also want to set up a more customized development environment. See [[Guidelines and HOWTOs/Build from source]].
 +
 
 +
 
 +
== Errata ==
 +
openSUSE users will need to make the following changes on their systems to support running KDE software built from source:
 +
 
 +
<ol>
 +
<li>{{Input|1=<nowiki>
 +
sudo ln -s qdbus /usr/bin/qdbus-qt5
 +
</nowiki>}}
 +
This fixes Spectacle global keyboard shortcuts until https://bugs.kde.org/show_bug.cgi?id=413007 is fixed. See also https://bugzilla.opensuse.org/show_bug.cgi?id=1158841</li>
 +
 
 +
<li>{{Input|1=<nowiki>
 +
sudo cp /etc/pam.d/kscreenlocker /etc/pam.d/kde
 +
</nowiki>}}
 +
This fixes the screen locker so that it will accept your password; otherwise you will need to log in via a TTY and use `loginctl unlock-sessions` to get into your GUI session. See also https://bugzilla.opensuse.org/show_bug.cgi?id=1158966</li>
 +
</ol>
 +
 
 +
 
 +
 
 +
== Best practices & other useful information==
 +
* [[Guidelines_and_HOWTOs/Debugging|Debugging]]
 +
* [[Guidelines and HOWTOs/UnitTests|Unit testing]]
 +
* [[Guidelines and HOWTOs/Code_Checking| Validating code]]
 +
* [[Guidelines and HOWTOs/API Documentation|Writing API documentation]] (related: https://api.kde.org).
 +
* [[Guidelines_and_HOWTOs/Wayland_Porting_Notes|Writing Wayland-friendly code]]
 +
* [[Frameworks/Porting_Notes|Porting from KDE 4 to Frameworks 5]]
 +
* [[Guidelines_and_HOWTOs/Making_apps_run_uninstalled|Running applications and their unit tests without first installing them]]
 +
* [https://community.kde.org/Infrastructure/Phabricator#How_to_review_someone_else.27s_patch How to review patches]

Latest revision as of 20:57, 10 December 2019

Konqui dev close cropped.png

By joining the ranks of KDE developers, you will get to implement new features and defeat bugs both daunting and simple, all while collaborating to make coherent and stable releases. Developers collaborate in teams based on what area they are working in. These can be small teams working on a single application, up to large teams working on a group of related pieces of software. Many developers are in more than one team.

KDE runs or participates in several mentoring programs to help new developers, including an informal list of people who are willing to help newcomers get started. See the Mentoring page for more details.

Dialog-information.png
Information
While any operating system can be used to patch or develop KDE software, it's easiest if you use a Linux distribution that provides relatively recent versions of Qt and KDE Frameworks, such as Arch/Manjaro, Fedora, KDE Neon, openSUSE Tumbleweed, or non-LTS versions of Ubuntu.

Support for distros that ship older software (such as Debian, Ubuntu/Kubuntu 18.04, and openSUSE Leap 15) is still experimental and you may have a better experience developing with one of the distributions mentioned above in a virtual machine.



New to C++/Qt software development?

Most KDE software is written in C++ using the Qt toolkit and KDE Frameworks. Though prior experience with these technologies or other programming languages is helpful, you don't need to be a C++ programmer to get started! For example, no programming knowledge whatsoever is required to do things like improve text labels.

If you'd like to dive deeper, the Qt wiki contains a list of online books for learning Qt programming. Qt also provides lots of examples you can look at. Information about KDE Frameworks can be found on the TechBase wiki, and a book is available.


One-time setup: your development environment

To build software, you need a development environment: a set of tools that allows you to access and edit the source code, compile it into a form that the computer can run, and deploy it to a safe location. We will now go through the process of setting one up. To accomplish these tasks, you will need to enter commands using a terminal program, such as KDE's Konsole (but any terminal program will suffice).

If you're not familiar with the command line interface, you can find a reasonable tutorial here. However advanced command-line skills are not required, and you will learn what you need along the way!

Note-box-icon.png
Note
Everything in this section only needs to be done once. Once you've done it, your development environment is set up and you can use it to submit patches and develop KDE Software!


Install basic tools

First you will need to use your operating system's package manager to install some basic tools:

  • Arch/Manjaro: sudo pacman -S git cmake dialog
  • Fedora: sudo dnf install git cmake dialog perl
  • KDE Neon/Kubuntu/Ubuntu/Debian: sudo apt install git cmake dialog
  • openSUSE Leap & Tumbleweed: sudo zypper install git cmake dialog



Configure Git

We need to set your authorship information properly so that any changes you make can be properly attributed to you:

git config --global user.name "Your Name"
git config --global user.email "[email protected]"
Note-box-icon.png
Note
The name you provide should be your actual name, not your KDE Identity username.

The email address you specify above must be the same as the email address used for your https://bugs.kde.org account. If they don't match, then the BUG: and FEATURE: keywords won't work (see this page for more information).


Set up kdesrc-build

Next, we need a method of managing dependencies. Every software has dependencies: other pieces of software that provide the functionality they rely on. In order to compile any piece of software, its dependencies must be available.

Most Linux-based operating systems do not provide development packages that are up-to-date enough for working on KDE software, so we will compile all the KDE dependencies ourselves. To do this, we use a command-line tool called kdesrc-build to download, manage, and build KDE source code repositories. Let's set it up now! First, we create a new directory for all the KDE source code we will be using. We then clone the source code repository that holds kdesrc-build in that directory, so we have a local copy of it on our computer.

mkdir -p ~/kde/src
cd ~/kde/src/
git clone https://anongit.kde.org/kdesrc-build.git  && cd kdesrc-build

Next, it's time to set up kdesrc-build and pick up the changes it made to your ~/.bashrc for the current terminal session:

./kdesrc-build --initial-setup
source ~/.bashrc
Warning.png
Warning
Do not quote or escape any file paths entered in the wizard! And do not run the command kdesrc-build by itself without any arguments because this will build everything, which is probably overkill right now.


The initial setup tries to install the basic packages for compiling Qt and KDE software on your distro. It also creates a ~/.kdesrc-buildrc configuration file. If you want a more guided setup process for kdesrc-build, run the command kdesrc-build-setup instead. However, unlike --initial-setup, it won't install packages from your distro for compiling programs so you will have to do that yourself.

Consult the kdesrc-build manual for more information and options.

Set up Qt

By default, kdesrc-build will build from source all the dependencies that a program or framework needs, including the Qt toolkit itself, because the include-dependencies option is set as default in the ~/.kdesrc-buildrc file.

If your Linux distribution provides a recent version of Qt (5.11 or newer), you can save some time and disk space and use that version instead of building your own. To configure kdesrc-build to skip building Qt, open the configuration file ~/.kdesrc-buildrc and comment out the qtdir and two include lines related to qt5.


Download non-KDE dependencies

Even though kdesrc-build will take care of the KDE dependencies for you, it does not yet have the ability to install non-KDE dependencies (see https://bugs.kde.org/show_bug.cgi?id=402428), which are typically acquired using your package manager. To install the required non-KDE dependencies, read this page and follow the instructions laid out there.

Once that's done, your development environment is set up and ready to build software! Let's take it for a spin.


Build some software

It can take an hour or more to compile a KDE Application, Framework, or Plasma itself for the first time. The reason for this is that kdesrc-build is compiling all of the KDE dependencies (See https://invent.kde.org/kde/kdesrc-build/issues/17). The next time you want to compile that or any other piece of KDE software, it will be much faster since most of the dependencies will have already been compiled. If you don't want to build all dependencies (e.g., because you are using a rolling release distro that provides recent versions of software), edit the same configuration file and simply set include-dependencies to false or add the --no-include-dependencies option when running kdesrc-build.


Applications

KDE Applications like Dolphin, Okular, Konsole and Gwenview are standalone apps that can be run on multiple platforms, such as Plasma, GNOME, even macOS and Windows! New versions of KDE Applications are released three times a year. Note that the Discover app store (git repo name: plasma-discover) and System Settings app (git repo name: systemsettings) are distributed alongside Plasma, but they build like apps using the below instructions. A list of all KDE applications can be found here: https://userbase.kde.org/Applications.

For example, here is how to build Dolphin, the KDE file manager:

kdesrc-build dolphin

As a part of this process, Dolphin was installed to ~/kde/usr/bin/dolphin. There is no need to manually install anything; kdesrc-build installed it for you! Source the project's auto-generated prefix.sh file every time you want to run your custom-compiled version of Dolphin:

source ~/kde/build/dolphin/prefix.sh
~/kde/usr/bin/dolphin

Did it run? If so, then congratulations, you just compiled your own version of Dolphin from source code!


Frameworks

KDE Frameworks are libraries of tools and features that can be used by any application or Plasma itself. New versions of KDE Frameworks are released once a month. A list of all frameworks can be found here: https://api.kde.org/frameworks/index.html.

For example, here is how to build the KIO framework:

kdesrc-build kio

Now you can run an existing app using your custom-made version of the framework! For example, the following will run Dolphin, but it will be using the KIO library that you just built:

source ~/kde/build/kio/prefix.sh
~/kde/usr/bin/dolphin


Plasma

KDE Plasma is the environment in which you can run apps. Plasma is responsible for providing a desktop with wallpaper, app launchers, and widgets; displaying notifications; managing wired and wireless networks; and similar operating-system level tasks. New versions of Plasma are released three times a year.

Here is how to build the Plasma desktop environment, including its window manager and its built-in apps:

kdesrc-build plasma-desktop plasma-workspace plasma-framework plasma-nm plasma-pa plasma-thunderbolt plasma-vault plasma-workspace-wallpapers kdeplasma-addons kwin systemsettings kscreen breeze discover kinfocenter --include-dependencies

To run your custom-built Plasma, first make it accessible from the SDDM login screen by running the following command:

~/kde/build/plasma-workspace/login-sessions/install-sessions.sh

If you don't have a plasma system you also need to edit the dbus session dir. create a file named kde-dev.conf in /usr/share/dbus-1/session.d and paste this

   <busconfig>
       <servicedir>/kde install dir/share/dbus-1/services</servicedir>
   </busconfig>

After that, you can log out and select your new plasma session in SDDM's session chooser menu (which is located in the bottom-left corner of the screen if you're using the Breeze SDDM theme).

How to solve build problems

Did one or more modules fail to build (displayed in red font) using kdesrc-build? Here's what to do:

  1. Try building the failing module again from scratch using kdesrc-build [failing module] --refresh-build
  2. Make sure that you have all the dependencies for the failing module. Go back to the #Download non-KDE dependencies section and re-install the non-KDE dependencies. If that doesn't fix the problem. Open the log file for the failing module, which kdesrc-build will print the path at the end of its output. Scroll to the bottom of the log file and read the output to see what missing dependency it is complaining about, then find and install the corresponding package using your distro's package manager your distro. If several looks relevant, install them all just to be safe.
  3. Check the list of currently broken modules on the KDE build server. If it's broken there, then it's not your fault. :)
  4. Ask for help in the the #kde-devel channel on Matrix or freenode IRC. See Get Involved/development#Communicate with the team


Choose what to do

Now that you can compile and deploy custom versions of KDE software, you can open your editor and start hacking on the source code! The code for the version of Dolphin that you built earlier is located at ~/kde/src/dolphin/; other projects you build with kdesrc-build will live in similar locations.

A good place to start is with a small bug or feature in an existing piece of software that affects you personally ("scratch your own itch"). Get in touch with the existing developers (see Communicate with the team, below) and they can help you out, by pointing you to the right place in the code and giving advice about how to tackle the problem.

Try not to start by proposing or working on major features or significant design changes. These can be controversial, and the smoothest way to get going is by working on relatively non-controversial bugfixes. Start slowly and build trust!

Here are some other ideas for starting points:

  • Improve awkwardly-worded messages and labels that are written in English. This is a great way for non-programmers to contribute! If you can compile software and have a good grasp of English, you can make a big difference here.
  • Work on Junior Jobs, which are small tasks that are suitable for beginners (both bugs and features).
  • Work on Bugs related to KDE's Usability & Productivity initiative, many of which are small and easy.
  • The English Breakfast Network searches out simple, common issues in code that should be fixed, and going through the problems on there can provide a good overview of the code.


Test your changes

Once you've made some changes, make sure the project still compiles and installs, and make sure the changes have the desired effect when you run the software. Then it's time to run the project's unit tests:

cd ~/kde/build/dolphin/
source ./prefix.sh
ctest --output-on-failure

If any test fails, that needs to be investigated and fixed before you can proceed. Once the tests pass, then run the software again to make sure it still behaves properly. If it doesn't, then go back and work on your patch some more, then re-compile and re-deploy, and test again, until the program does what you'd like it to do and all tests pass.


Submit a patch

Once you're happy with your patch and have verified that it does what you want, it's time to generate a diff. A diff is a textual representation of the differences between original versions of the files you changed, and the new ones you've produced. You can generate a diff by entering the source repository and running git diff, but we recommend using the arc tool, which will generate a diff and submit it for review very quickly and easily! You can learn how to set it up here.

KDE uses Phabricator for patch submission and review. Learn more about how to submit a patch with Phabricator.


Communicate with the team

There are several ways to get in touch with KDE developers, either generally or for a specific project. The most important communications channels are:

These are general KDE development communication channels, and you may get directed to a more appropriate place for the project you are interested in. There is a list of mailing lists if you want to find a mailing list for a specific team directly. Many teams have their own real-time chat channels, too.

You can also try looking for the team's section on the Main Page of this wiki. Many teams have information there for new contributors.


Next steps

Sharpen your skills by going through the KDE development tutorials. And try out KDevelop, the KDE IDE.

After you have had several drama-free patches accepted, a KDE developer is likely to suggest you get a Developer account, which will allow you to commit directly to KDE projects. With very few limits on where you can commit, you will be expected to act responsibly. At this point, congratulations! You are officially a KDE developer!

You may also want to set up a more customized development environment. See Guidelines and HOWTOs/Build from source.


Errata

openSUSE users will need to make the following changes on their systems to support running KDE software built from source:

  1. sudo ln -s qdbus /usr/bin/qdbus-qt5
    
    This fixes Spectacle global keyboard shortcuts until https://bugs.kde.org/show_bug.cgi?id=413007 is fixed. See also https://bugzilla.opensuse.org/show_bug.cgi?id=1158841
  2. sudo cp /etc/pam.d/kscreenlocker /etc/pam.d/kde
    
    This fixes the screen locker so that it will accept your password; otherwise you will need to log in via a TTY and use `loginctl unlock-sessions` to get into your GUI session. See also https://bugzilla.opensuse.org/show_bug.cgi?id=1158966


Best practices & other useful information


This page was last edited on 10 December 2019, at 20:57. Content is available under Creative Commons License SA 4.0 unless otherwise noted.