(This post has nothing to do with Aaron's gitit post - different topic altogether) I was building OpenIndiana packages of KDE 4.6.2 (the plasma workspace and some of the application bundles, to start with) when I encountered a compile error. Simple enough fix, too: add a single newline to a file in plasma-addons. That's a little oddity in C++ source files, they must end with a newline, and it is particularly important if the last line is #include.

Hence. motivation to actually get git, get a checkout, and commit the fix back to upstream. I know I'm set up for all that, through identity.kde.org (register for developer accounts), and I know KDE SVN well enough. But never git.

So where to start? That was the question for me. And I found that the existing documentation leaves something to be desired in terms of discoverability. Here's a first shot at some extra tekst to document it a little better.

The question I have is "how can I get KDE source, make a change, and commit it?" This presumes a properly set-up KDE developer account via identity.kde.org and working SSH with that developer account. A scripted build is not what I want (even if doing one would probably get me the required files behind-the-scenes).

My starting point is KDE TechBase. Good thing: there's a "setting up a KDE development environment" right on the front page. (Please note that the TechBase pages are always being updated and there's some work going into documenting these things better already, so some of my issues may go away -- maybe go away faster if someone cuts-and-pastes some of this into TechBase itself).

Clicking through the Getting Started bit, I end up in the section Obtaining the Source Code, which forwards me on to projects.kde.org. There's mention of source snapshots, but those are for SVN, not git.

I find the front page of Projects a bit intimidating, but that's because it's such a big list, and some projects have descriptions and last-modified information and some don't. Calligra could definitely use a better description -- "we do stuff with things" is not a successful tagline for projects, even when Paul Adams is involved.

OK, so "obtaining the source" sent me here, and I can find the repository I know I'm interested in, namely KDE Plasma-addons. That page doesn't tell me a whole lot, but I can click on the "Repository" link as a best guess. Once there, the "SSH" button gives me the git command to enter (in a terminal) to actually get the clone of the repo. That command looks like so:

git clone git@git.kde.org:kdeplasma-addons

Having reached this point, I can take the command apart and presume that "kdeplasma-addons" is the name of the repository. Other repo names are "kdelibs" or "kde-baseapps" or "kde-workspace" or "kdepim" -- there's dozens, but having the scheme clear once helps.

So here's my additional blurb for the "obtaining the source" section:

To get the source of a particular (sub-)project from git, find the name of the git repository at projects.kde.org. The name can be found by clicking on the "repository" button once you have navigated to the page for a given project.

For read-only access (e.g. to keep up-to-date but not to push your own changes), use the URI git://anongit.kde.org/ . For read-write access, use the URI git@git.kde.org: . In both cases, the command to get the sources is then git clone , e.g. for the plasma-addons project the complete command for read-only access is

git clone git://anongit.kde.org/kdeplasma-addons

I believe that adding some text like that so that it's clear where you'll be navigating to would make things a bit less intimidating to folks just starting with the git infrastructure for KDE.

Anyway, once you've got the source code you still have to deal with the rest of the git workflow, but I imagine that will be documented at some point (I seem to remember someone on planetkde pointing to several tutorials recently). I just pushed my first ever change to KDE git (less daunting than I expected). If Lancelot is now broken, you know who to blame :)

PS: and if you're wondering why I didn't just go and add that to TechBase, it's because I'm not sure that it's entirely (a) technically accurate (b) appropriate at that place in TechBase. I'll leave it to TechBase editors to think about that.