Summer of Code Mentoring HOWTO

Federico Mena-Quintero

License.  This work is licensed under the Creative Commons Attribution-Share Alike 3.0 Unported License. To view a copy of this license, visit http://creativecommons.org/licenses/by-sa/3.0/ or send a letter to Creative Commons, 171 Second Street, Suite 300, San Francisco, California, 94105, USA.

Availability.  The latest version of this document is always available at http://www.gnome.org/~federico/docs/summer-of-code-mentoring-howto/.

Revision History
Revision 1.22008/March/25

Added a Creative Commons BY-SA license. Added a section on Availability.

Revision 1.12007/March/15

Improved the wording to make it more gender-neutral.

Revision 1.02007/March/08

Initial version.


Table of Contents

Motivation
What you need to be a good mentor
Keeping yourself and your student organized
Care and feeding of students
Starting the project
Day-to-day work with your student
Ending the project
Introducing your student to the community
Finally

Abstract

The Summer of Code, initiated by Google, is a wonderful opportunity for students to learn how to contribute to free software in a short time, while making a nice chunk of money in the process. Each participating student gets a mentor, who is normally a member of an existing free software project. This document intends to give some advice to mentors, so that they'll be able to help their students to complete their projects successfully.

Motivation

During the first Google Summer of Code (GSOC) in 2005, I mentored one extremely bright student for the GNOME Project. He did a pretty good job, but nevertheless I felt that I had been a terrible mentor. I rarely communicated with my student, didn't really know the status of his project, and I don't think I ever provided any real help to him.

A year later, in 2006, I decided to be a better mentor. I coached two students, one for GSOC and one for GNOME's sister project, the Women's Summer Outreach Program (WSOP). Once again I had the fortune of getting two extremely bright and enthusiastic students. Both were quite successful, well beyond my expectations. This time, however, I felt that I did a much better job of mentoring them and leading them through their project. I want to share some of the knowledge about how to be a good mentor for projects similar to the Summer of Code.

What you need to be a good mentor

First, you need time. Be prepared to dedicate at least 30 to 60 minutes every day to your mentoring. There will be exceptions, such as days when your student is not online. But in general, you need to be able to dedicate a relatively large amount of time to your student. You will be communicating with her, clarifying doubts, making plans, checking her work, reviewing patches, communicating to other people about your student's work, or just chit-chatting.

Second, you need to dedicate a good extra two hours every week to test your student's code or otherwise evaluate her work. Nothing is more demoralizing than a mentor who talks to you but doesn't actually see the fruit of your work in front of him.

Third, you'll be mentoring on behalf of a project, or part of a project ("the file manager in GNOME"). You must know the code for this project or sub-project really well. Your student has probably never had to do anything with that code. You are the person who will answer her questions about where in the code something happens, or how the code is supposed to work in the grand scheme of things. Remember the first time you had to modify a big program: that's exactly how your student will feel, so you have to be prepared to answer questions about the actual code.

Fourth, you must have a clear vision of what your student wants to accomplish. If you cannot see the finished "product" in your mind, you won't be able to communicate clearly with your student. This automatically rules out projects that are too experimental or imagined by architecture astronauts.

Keeping yourself and your student organized

You have your daily work, hobbies, and personal things to do. On top of that, now you have to coordinate and manage another person: your student. What do you do?

Keep a journal or log of what your student does and of what you ask him to do. You don't need anything fancy to do this: maintaining a text file, ~/summer-of-code/student.txt is enough. The following is an actual sample of the log I kept for one of my students:

Cecilia González <m3gumi@gmail.com>
http://m3gumi.wordpress.com/
http://bugzilla.gnome.org/show_bug.cgi?id=352628

*** TO-DO:

+ 2006/Jul/17: Put a timer in e_shell_window_switch_to_component()

+ 2006/Jul/17: See the possible component_ids that can get passed
  to that function.

- 2006/Jul/13: Get jhbuild to work

- 2006/Jul/15: Do an initial run of sysprof

*** LOG:

2006/Jul/10:
- Cecilia has been having trouble with jhbuild.  Had a lot of trouble
  building gtk+/cairo; gave her some advice.

2006/Jul/13:
- Still trying to get jhbuild to work for all modules.  Stuck on
  Avahi (she's on Debian Unstable).
- Found Cecilia's problem; it was PKG_CONFIG_PATH pollution from
  outside jhbuild.
- Another thing: her .bashrc had "PATH=/bla/bla:/foo/foo" instead of
  the usual "PATH=$PATH:/bla/bla:/foo/foo", so it was *overwriting*
  jhbuild's values when run as a secondary shell by jhbuild.  Thus,
  the wrong programs were picked up.

2006/Jul/14:
- Evolution runs!
- Cecilia will start looking at how to automate component switching
  with LDTP, and how to run the profiler.

FRIDAY SEPTEMBER 1 IS "PENCILS DOWN"!
      

1

Name of your student and contact information. When you are mentoring more than one person, this can come in especially handy to cut&paste their email addresses — you'll remember your students' names just fine, but probably not their emails!

2

Useful URLs that you find about during the course of the project. Here, the first URL is Cecilia's personal blog about the project; the second URL is the bug report which she opened to get her patches reviewed.

3

Pending tasks are marked with a "+". This makes it easy to search for them in your text editor.

4

Completed tasks are marked with a "-".

5

A log of what your student has done. It is very useful to have this information, so that you can review it the next time you talk with your student. It will serve to remind yourself of what you were discussing the last time you talked.

6

Finally, after the end of the log, write the deadline in which your student must turn in the finished work. ALWAYS KEEP A MARKER WITH THE DEADLINE! When you append to the journal, this will remind you every day of how much time you have left to complete the project.

Maintaining this log of activities can be very useful. You can use that simple text file to paste chunks of IRC/IM conversations, interesting URLs, bits of patches, or anything else that will help you remember what your student is up to.

I stole this format (with the "+" and "-") from Michael Meeks, as I want to be as productive as him when I grow up.

Care and feeding of students

IRC and IM are fine for day-to-day chatting with your student. In this modern age you may even be able to set up Ekiga or some other VOIP software — but don't waste too much time setting it up if it doesn't work at first. See the section called “Starting the project” below for how to pick a good time to chat with your student.

Use email for detailed technical explanations; it is much better for that than IRC/IM, and it will be much easier for both you and your student to keep those emails around for reference.

Your student knows few people in your project's community, and she is not used to all the informal or formal processes which that community has defined. You must take care of all the bureaucratic little details for your student. For example, if your project requires your student to wait for a sysadmin to create a CVS or Subversion account for her, then you should ask the sysadmin to do so as soon as possible. In general, help your student so she doesn't have to waste time waiting for administrative things to happen.

Guide your student through the code. You have been working with it for years, while your student is probably looking at the code for the first time. Teach her all the little debugging tricks that you have amassed over the years.

Your student wants and deserves recognition. Advertise your student's work far and wide! Every time she reaches an important milestone, do whatever it will take for people to notice: blog about it, send a screenshot to your project's mailing list, etc. People will get interested and they will contact your student; your student will feel appreciated as a result.

Make sure your student uses a revision control system for the code. CVS/Subversion/Git are all fine. Also, teach your student the basics of Bugzilla or your project's bug tracking system if appropriate.

Very important: if your project uses a nontrivial build system, a sandbox environment, or anything similar (for example, jhbuild for the GNOME project), teach your student how to use it and make sure she can get the code compiled and running very early in the project. This is in the same spirit as helping your student with silly administrative details: you don't want your student to waste time getting the code to compile; help her out!

When your student gets stuck, help her to think laterally. Why do you think the problem is happening? Can you solve it in a non-traditional way? Tell her key places in the code to put debugging printf()s. Tell her the little tricks you use in your debugger. Only if she gets *really* stuck, solve that little part of the problem for her, but in general try to help your student solve the problem herself.

Starting the project

Talk to your student (via email or IRC/IM) to find a time that is good for both of you to chat every day, and stick to that time. A time that worked well for me (in Mexico) was to have my students chat with me at during 9:00-10:00 AM, right before I begin my normal workday. My students were both in Europe, so this was a relaxed time in the afternoon for them. Synchronizing with them in the morning was good for me, since my brain was fresh after waking up, and I could schedule 100% of it to my students instead of being distracted by my normal work.

At the start of the project, ask your student to write down her goals and a rough timeline or schedule. Make sure the schedule has time for bootstrapping: getting her to build your project for the first time, fixing any problems she may find with the build system, setting up her CVS account, etc. Bootstrapping should not take more than a week: help her attain that goal. Make sure the schedule has a few days at the end for a final report.

Day-to-day work with your student

Poke your student about pending actions periodically. Don't say, "have you finished this yet?", but rather, "do you remember when talked about <blah>?". Your student will then understand that you really want that done at some point.

Do ask your student if she's getting stuck. Students tend to be shy when they have problems; they are afraid that they'll ask dumb questions. Not so! Remember that you have much more experience than your student with the piece of code she is studying, so you can always lend a hand.

Keep your log file up to date. What did you talk about with your student? Did you give her "homework"? Did the student give you links to new patches, mockups, etc.?

Run your student's code! Send her a patch or two. Make a suggestion about the code's organization. This will encourage her further by showing that you actually care about her code. And of course, this will give you the chance to really see the status of your student's work. Remember that working code is more important than big ideas.

When your student reaches a significant milestone, advertise this far and wide. Blog some screenshots, mail the mailing lists, make some noise. This will encourage other people to look at your student's work and someone will inevitably mail her with praise and suggestions. This makes for happy students.

Make your student do The Right Thing as much as possible, i.e. to avoid quick hacks or to avoid leaving her code undocumented. If your student is doing profiling, make her write profiling tools and generate pretty charts. If she's doing coding, make her match the workflow and style of the rest of your project.

Be nice to your student. Ask him a bit about her life; do some chit-chat. Find out your student's tastes in food. Promise to buy her a coffee or a beer when you meet in person. All work and no play makes for a dull Summer of Code.

Ending the project

Near the end of your student's project, allocate time for your student to write a final report. This doesn't need to be a formal document. It just needs to have things like these:

  • A buildable tarball of the final code, if it's a new program.

  • A set of patches, if it's modification to existing programs. Make sure the patches are filed in the appropriate bug-tracking system, or whatever other method your project uses to keep track of pending patches.

  • A little write-up with the analysis of a performance problem.

  • A description of any pending work which there was no time to do. This will let someone continue the project after the Summer of Code is over; or if your student wants to continue, it will give her a good reminder of what remains to be done.

  • A single web page with links to all of the above.

This last item is the most important one: the world needs a single place to look at everything your student was able to produce. Google will use this to evaluate the student, and it will be the "portal" through which other people can look at her work. Doing this will also let you and your student know whether there are any loose ends that need to be tied.

Introducing your student to the community

If a good number of the people involved in your project attend a conference in the middle of the Summer of Code, by all means get your student to go. Meet her in person if possible. Buy her a beer. Introduce her to the important people in your project. Make your student be aware that she's part of the community now, and that her work is loved and appreciated.

Make your student subscribe to your project's development mailing list. Make her read your project's blog aggregator. Get her into the loop! Make your student feel part of the core developers.

Point your student to the right people. Your student is shy and sees you and your team as bearded elders who are too important to bother with anyone. Not so! Show him her we are friendly hackers full of love for smart people.

Whenever your student's code becomes good enough for general consumption (even if it is just for the developers), make the rest of your team actually use your student's code. She'll start getting patches and feedback, which will make her feel even more appreciated and smart.

Have your student go through the proper motions to submit her patches: send the patch through Bugzilla, write proper ChangeLogs, create "proper" patches (same indentation, good comments, "diff -up", etc.). Your student has probably never done this, so teach her how!

See if your student can keep a weblog of her work. Then it can be aggregated into your project's Planet, and people will see your student's progress. You can also put it on your own aggregator and get daily updates of your student's work each morning.

Finally

Empathize with your student. She's not a hard-core free software hacker at the center of the community like you are. Teach her the ropes, introduce her to the right people, and show her that even superhackers are friendly to newcomers who are willing to help.

The Summer of Code is not about churning out perfectly working code, or about slave labor. It is about putting a lot of highly-focused energy into jump-starting new hackers into free software. (Okay, it's also a recruiting vehicle for Google, but that's another story) :)

Have fun during the Summer of Code!