A Usability Guy’s Journey to Creating his First KDE Tool – Part 1: Baby Steps
I, psychologist by education, human-centered interaction designer by trade – my only completed software project so far being a web-based Advent calendar I made years ago – have embarked on a journey to write my first KDE tool. How did it come to this?
It all started with me wanting two things:
- To change the speed of Plasma animations on my system
- To have proper AppStream metadata for KDE software
These two may sound completely unrelated at first, but they both were key in sending me down this path. This article will tell the story behind 1, which is about my very first code commit to KDE. I will go into quite some detail because I feel that my journey may provide some insights for KDE.
This story started on April 6th. I was discussing with Aleix Pol about actual vs. perceived performance in Plasma and other KDE software. One thing we agreed on was that animation speed has a big impact on perceived performance. During that discussion, we found out that the setting for the animation speed is almost impossible to find in System Settings, because it sits in a module where you would not expect it to be (Display and Monitor > Compositor), and searching for “animation speed” points you to the wrong module (this was due to an oversight when the “Desktop Effects” module was split in two and the search keywords were not adapted). The “it sits in an unexpected module” problem is about to be fixed by moving it into the “Workspace behavior” module, but first I wanted the actual bug with the search pointing to the wrong module to be fixed.
At first, as usual, I wrote a bug report about it. Then, Aleix, being a cunning little Spaniard (*scnr*, I know you’re Catalonian), said these fateful words: “You could fix this one yourself!”. Now the cunning part was that he knew I could not defend myself by saying “But I don’t know C++ …” because the search keywords are defined in .desktop files, easily read- and writable for mere mortals like me. So, without any good argument why I couldn’t, I set out to fix it myself.
The first obstacle on my journey was that even after years of being a KDE contributor, I still did not have a KDE developer account. The reason is simple: My contributions usually come in the form of text and mockups, not code. I describe my ideas in wiki pages, emails, forum posts, chats, review requests, bug reports, blog posts, …, but not in repositories. For this simple patch, I could have just put it up on Reviewboard or Phabricator and have someone else commit it, but if I was going to contribute code, I wanted to do it properly™.
Besides, I saw an opportunity in this exercise: We often hear that while new contributors perceive KDE as a very friendly and welcoming community, they perceive the organizational process of becoming a KDE contributor as relatively difficult, and now I could experience that process first-hand and see what could be improved. So I wanted to go all the way.
Now first of all, I needed to get a developer account. I know that community.kde.org is supposed to be the place where every information for the community can be found, so I looked there. The “Get Involved/development” page looked promising. And indeed, this had a link to the “Get a Contributor Account” page. Here I found the first inconsistency: On the page, it was called a “contributor account” whereas in the actual application process it’s called “developer account”. I have fixed that now, changing (hopefully) all of it to “developer account”. “Developer account” made more sense to me, because – as evidenced by for example by me – not all contributors need such an account. Apart from that, though, the documentation there was pretty straightforward.
With that and Aleix’s blessing, I had my Developer account created the next day. Now the more difficult part was setting up Git.
The “Get a Contributor Account” page (which will hopefully soon be renamed by someone with the necessary privileges) had a link to a “next tutorial” in the “And now?” section which in turn was just linking back to the page you came from, along with something about me having to adapt my local copy to a new server (without further specification). I did not understand that part, so I asked Aleix what it meant and now we have made it more specific.
Olivier Churlaud, our new Master of the Wikis, then pointed out to me that the best pages for further information would be the Git or Subversion pages, depending on the project one wants to contribute to, so I’ve now linked to those from the “And now?” section.
So, next step, setting up Git. I followed the steps in the “Git Configuration” page, which involved a tedious amount of “git config –global” commands. I wonder if maybe we should provide a template .gitconfig file to make this easier, at least for things that are ideally the same for anyone, anyway? One of the instructions in there told me to enter
git config --global user.name <Your Real Name>
so what I entered was
git config --global user.name Thomas Pfeiffer
Following the instructions by the letter bit me in the behind later on when I tried to commit, because of course Git ignored the last name after the space and then the server could not identify me. Without Aleix’s help, I’d never have been able to identify the problem, let alone fix it.
This may all be obvious for seasoned shell users, but it clearly wasn’t obvious for me, so I changed the instructions on the wiki to
git config --global user.name "<Your Real Name>"
just to remind people to put their name in quotes.
The page also recommended to use the Git commit template from kdelibs. This sounded outdated to me given that kdelibs is long deprecated by now, but since I wasn’t aware of any other commit template, I went ahead and used the one from kdelibs, anyway. I’ve now started a discussion on the kde-devel mailing list regarding where we should put that template in the future.
Aleix suggested that I’d use Arcanist to link my commit to a review on Phabricator, but since I didn’t want to install another tool just for my one commit (and Arcanist was never mentioned in the pages I’d come across on the wiki, either), I decided to skip that for the time being. So I manually created a Diff on Phabricator (like the “Get Involved/development” page had told me), which was reasonably simple.
Now it was time to actually commit and push my changes. For that, the page “Infrastructure/Git/Simple Workflow” sounded like the most fitting one to follow. I did what I was told there to add and commit my change. Now for the commit message. Following the link trail from the Simple Workflow page lead me (through one unnecessary hoop which I’ve now cut out) to the “Special keywords in GIT and SVN log messages” section of the “Commit Policy” page.
There I found what I was looking for, except for how to link to the Diff on Phabricator (I’ve added that now). With my commit message complete, I could finally push. I was asked whether I should add the server with the fingerprint SHA256:75pLvlr+9A0ki9YlWAz+il4UPI+N81uMvcocs42d0wU to my list of trusted servers. I remembered that the Git Configuration page had also mentioned server fingerprints, but unfortunately, those did not match the fingerprint Git presented to me. Aleix told me that the server was okay and the page was just outdated. Accepting a fingerprint which does not match the one you find in the documentation of course defeats the purpose of putting fingerprints in the documentation in the first place, so we have to either remove them from the wiki (I did that for now) or find a way to keep them up to date.
Now, finally, my first commit was pushed! Closing the bug automatically failed, unfortunately, because I had not heeded the advice in the page about getting a developer account which said “Also note that this email address should be the same one that you use on bugs.kde.org“. This one’s on me, then.
So, this is the story of my very first commit to KDE! I learned a lot along the way, uncovered some slight shortcomings in our documentation and fixed most of them. I can say that trying to relive the first contribution experience first-hand is a good lesson for anyone who cares about improving it.
In the next posts of this series I will expand on that by creating my own little tool for making the creation and updating of AppStream metadata for KDE applications easier, and I will be doing it in the way I know best: the user-centered way.
Have you started contributing to KDE recently, or know someone who has? If so, please let us know about your experience! What went well, where could we improve our onboarding process in KDE? Tell us in the comments!
Comments: 8
Thanks Thomas Great post.
How are these related – Reviewboard, Phabricator, QuickGit?
I suppose you are probably going to write about how you could fix that problem without the knowledge of C++/QML.
Good point about Reviewboard vs. Phabricator. That is something I’m simply taking for granted by now because I’m so involved in KDE, but it’s definitely confusing for newcomers.
Are there plans to replace one by other as they both seem to do the same job? Can anyone get a developer account at KDE?
They both currently coexist as a transition from Reviewboard to Phabricator. As far as I know, the goal is to phase out Reviewboard and only leave Phab.
Basically, anyone can get a developer acount at KDE. Usually a new developer starts out by submitting a few patches on Reviewboard / Phabricator and getting to know the community better, and when the others are convinced that the developer is both trustworthy and qualified to be given direct write access to all of KDE’s repositories, they can get a dev account.
[…] Usability Guy’s Journey to Creating his First KDE Tool – Part 1: Baby Steps https://sessellift.wordpress.com/2016/04/22/a-usability-guys-journey-to-creating-his-first-kde-tool-… #kde #gnu […]
@Thomas, good post; and your writing is consistently good: it makes me want to contribute.
Even as a “seasoned developer” when you want to join a new community the instructions are often baffling. The source control and release management stuff I do every day, I can do without thinking too hard, but it probably took 6 months to reach that stage. The new instructions are both too similar and too different to what one has been using.
It is also hard for many people to ask the right questions, for fear of looking stupid or knowing enough foundation to know what questions to ask.
Awww, thank you!
Getting people thinking was the goal of this post. Getting people like you wanting to contribute is more than I could ever hope for 🙂
Also if – by showing that getting started with code contribution can be difficult even for someone who’s been in KDE for years – I can ease other new contributors’ fear of asking “stupid questions”, that would be great!
[…] A Usability Guy’s Journey to Creating his First KDE Tool – Part 1: Baby Steps […]