Monthly Archives: February 2014

Merging long-neglected user help

When I first started contributing to GNOME documentation, it was not unusual for members of the Documentation Team to not have accounts for Instead, the team often worked on other infrastructure such as Gitorious. While in theory this is a good idea as it means that new contributors don’t need to have access to GNOME infrastructure, in practice, there are a number of drawbacks. The worst of these is when work on the user help stalls and is then forgotten about. This happened to a number of projects such as rhythmbox and gnome-system-monitor and in some cases, newcomers to the team started work from scratch when it was almost complete elsewhere, of which even I was guilty on one occasion when I first started contributing. At our last winter hackfest, we got our backsides into gear and finally moved all of the pending work that we could find to branches on

utilities-system-monitorOne of the tasks that we took on last year was to merge the gnome-system-monitor help to master. Unfortunately, there was a licensing issue. By “licensing issue”, I mean that there was no license for the work that had been done. The first thing we try to do in these cases is to contact all original contributors and ask them to add the license. This (eventually) works in about 80% of the cases, although it can take a few months for everyone to agree to the changes.

If we have lost touch with one or more of the original contributors, then it becomes a bit more complicated. In those cases, the only option left is to delete all the work that has been done by them and rewrite those parts from scratch. This is what we had to do in the case of gnome-system-monitor. Phil and Mike did a good job of fixing up the bits that needed while I reviewed some of the pages.

At this point, the user help has been in some form of existence where the content was almost good enough for merging for over 3 years. With the licensing issue resolved, the help was finally merged to master in the last couple of days. Within half a day, it was already half translated into Spanish by the awe-inspiring Daniel Mustieles. There are still a few improvements that could be made, such as restructuring the index to fit with the style of the other help and trying to shorten some of the page titles.

I was building gnome-system-monitor after every one of my commits and rebases while preparing it for merging. Once the help was merged, someone else who was trying to build it came across an issue that was likely caused by the removal of the old DocBook help and addition of the new Mallard help, where the Makefile was not regenerated properly. This problem was easily fixed by running git clean -dfx, which force-removes untracked files and directories while not using ignore rules from .gitignore.