Currently the KWin team is rewriting the work of two past Google Summer of Code projects. This is of course the worst thing which can happen about the projects. In retrospection we clearly have to say that the projects actually were failures – at least for the developer community. But both students succeeded their project, so we cannot say it’s the fault of the students. On the other hand the projects had different mentors, so blaming the mentors is too easy as well.
In this blog post I want to reflect why we consider the projects after more than one (respectively two) years as failures. What did go wrong and what can be improved in future projects? I hope this can be a help for more projects than just KWin.
I will base all examples on scripting – the project I am currently rewriting. Just to give an example of the scope: when scripting got imported into trunk it consisted of 3200 SLOC and now after the rewrite is almost finished it is down to about 500 SLOC which are mostly written by me. At the same time the provided functionality increased.
Don’t expect Students to Understand Complex Code
The scripting project should make it possible to have scripts run when “something happens”. E.g. if a window gets maximized the scripts should be notified. In the Qt way the best way to achieve that is by emitting a signal. Now this is what our student did. But in all cases I found so far the signals were emitted in the wrong place. So what is wrong?
KWin core works in a way that a user action triggers a method. E.g. entering the fullScreen mode will end up in Client::setFullScreen. But this method does not just perform setting the window to fullScreen, it also evaluates first whether it is feasible to set the window to fullscreen. For example the user might have established a window specific rule to disallow this window to go fullscreen. In that case the method will not change the state of the window.
The common pattern our student introduced was to emit the signal before the method had evaluated whether the window will change the state. So the scripts are notified with potentially wrong state change information.
Of course we cannot expect that the student for whom the code is completely new will understand these concepts. If you don’t know the internals of an application the behavior is in fact unexpected especially if it is only partially documented or commented.
Given this experience it is important to give a student enough time to get familiar with the rather complex code base. In this time it is important to provide the required help. In the example above it would have been a good advice to emit the signals whenever the effects are invoked – which happens at the same place (nowadays the notification of scripting and effects are merged) through direct method invocation.
Work in master
The Scripting GSoC got implemented in an SVN branch. For me as a team member and not being the mentor it was difficult to follow the development. In the end the branch got merged into SVN trunk without a review done by the team.
Some of the issues are resolved nowadays thanks to the git migration. So even if a student works in an own branch the team mates would get the commit mails and would be able to do a post-commit review on each commit. But still working in a branch for a long time brings disadvantages. Most likely the student is disconnected from the work. The team mates might work on the same code area, making merging more difficult – especially for a young developer who also has to learn to work with a complex VCS such as git.
So I think that it is most important to have the work been done in master (or any other development branch) directly. This might be tricky as KDE SC’s release schedule does not align well with GSoC, but as soon as the release branch is created there is no reason to not work on master.
Even while master is frozen the student should follow the common pattern and propose each change as a Review Request. This gives early feedback to the student and moves the burden of mentoring to the shoulders of the complete team. The team mates know what the student is working on and can provide early help and spot potential problems even if the mentor does not spot them. Remember: it’s not your student, it’s the team’s student.
Interfere before the student runs in the wrong direction
One of the tasks of a mentor should be to provide guidance to the student and ensure that the project goes in the right direction. I remember that my mentor did exactly that at one point were I started to do fancy stuff.
In case of the scripting project the student started to implement a kind of JavaScript extension for “Lazy Logic”. This was clearly not in the scope of the project, it might have been fun to implement for the student, but it’s nothing which is needed in a window manager. That’s just the wrong place to design new language features for JavaScript.
Given that the code was undocumented and I did not find any documentation explaining how this language feature works or why I would need it and last but not least I did not understand the code, it was one of the first code parts I dropped. This would not have been needed. The student should have concentrated on the task he is proposed to do.
Remember that the world is round
Yes, there are time zones. Yes most mentors have a day job and are restricted in the time they are available. It is no help to the project if the student works while the mentor sleeps and the student has to wait a day when he needs to ask questions to continue the project.
I remember that we had one project with the student living in Mexico and the mentor living in Australia. Of course this is a rather sub optimal combination. Don’t expect that the student will adjust his sleep rhythm. Even as a GSoC student he has the right for a normal social life.
Personally I decided not to mentor a student who doesn’t live in a European timezone. I just acknowledge with that, that I am constrained in time and that also all team members live in Europe, so we just cannot mentor students living on the other side of the world.
Communicate!
Communication is in my opinion one of the central aspects for a successful projects. During the project I mentored last year I tried to discuss the state of the project each day. And with communication I do not only mean e-mail or IRC, but also phone and personal meetings. If you live close to each other it might be a good idea to meet at least once, if the student lives in Europe Akademy is a must!
But communication is not only important with the mentor. Also with the complete team. The student should subscribe to the mailing list, read and answer review requests, be present in the IRC channel. His project benefits from it and the chances are better that the student stays after noticing how great the KDE community works.
Require Documentation
No code should be merged without documentation and without unit tests (if your project uses them). There is no excuse for a young developer to not write documentation. If the student works on a new area of code it is extremely important to have everything documented in a way that any of your team members can continue working with the code.
In case of scripting the code was lacking any documentation not even a high level description of the design was provided. This made it impossible to continue to work with the project. Trying to understand undocumented code can be more difficult than rewriting from scratch.
During a GSoC project you have the chance to enforce documentation. Make it clear that the student will not pass the final evaluation if the code is not documented. Documentation is not a nice candy, but at least as important as the code itself. Undocumented code is just unacceptable in the year 2012.
Be Prepared for the Worst
The worst for the developer team is that the student stops working with the last day of GSoC. This is bad but happens. The team has to be able to take over the project. A code dump is no solution and in doubt better not merge in the project than introduce bugs and instability. Yes that means that a GSoC project was wasted but it prevents a degeneration of the code base and does not bind your teammates to fix up the code.
In case of scripting we got a code dump which was completely undocumented and basically we have never seen anything of the student again. For me it would have been easier to just write the bindings from scratch than to fix up the project. Between the end of the project and my rewrite I had to fight several times with strange things done in scripting. So overall the project costs for the core team were higher than the benefits.
Adjust the proposed projects to the fact that the student will not be around after the project. $SUPERAWESOMEFEATURE is just bit crap if it cannot be maintained by your team. Use projects were you are sure that it will benefit the team even if the student will never touch the code again.
Adjust Your Own Expectations
Many mentors try to get just “cheap” work done and have the dream to get a new team member which might some day replace their position in the team. This might happen, but is rather unlikely. If that is your aim, you might head in the wrong direction. Now I can say lots about it, but there are people who can do that better, so I recommend to read the slides by Leslie Hawthorn from this years linux.conf.au.
The KWin team has learned from the experience with our failed projects. During last years project I was holding the hand of my student. For me it was important to get good code written and not much code or have him working on new areas. Also this year I will not mentor a project which would introduce a new area in KWin. E.g. Wayland support is out of bounds for a GSoC.