Tips for Google Summer of Code students
This is an assemblage of advice that applies to every GSoC student. Consider this a FAQ without questions.
Your mentor may give you advice or instructions that conflict with this list. He takes precedence; do what he says.
Commit early; commit often
Don't be afraid to commit your changes. That's why we have branches and version control. We're not worried about you breaking stuff as long as you work in your branch; if you do break something, you (or your mentor) can always fix it or revert it.
Branches exist for big features, like the three-month arc of a GSoC project. The idea is that you create a branch so that work on the feature can progress and be committed to the repository without breaking the trunk code that people who aren't involved with the feature will be using. We only get mad if somebody breaks the trunk; stick to your branch, and you'll be fine.
Make sure it builds
Your mentor wants to test your work (and has to, for the two mentor surveys). He can't test it if it won't build for him. So don't commit it unless you can build it. Even if it's broken at runtime, it should at least build.
Know what you're committing
Before you commit:
- Use svn st (or svn status) to see what files are unknown to svn (?), added (A), deleted, (D), and modified (M).
- Use svn add to add any unknown files that you want to commit. You need to do this whenever you add a new file (e.g., a new class) to the project; svn won't know about the file until you add it, and it won't commit it unless it knows about it.
- Use svn diff to see what changes your commit will effect. Sometimes you forget to take out an NSLog or AILog, or forget to delete some commented-out code (see next section). You can pipe the output from svn diff to a pager; for example, svn diff | view - (note the ‘-’) to use vim, or svn diff | less to use less.
File tickets
The Trac system is a really fancy to-do list. Use it to your advantage. In particular, don't just keep your plans in your head, much less on paper or in a local file you keep to yourself; instead, file tickets, so we can all (users and devs alike) plan and discuss solutions and watch your progress.
Make sure you set the correct component in your ticket. With few exceptions, every GSoC student gets a component in the Trac for tickets specific to their project. This may mean you; ask your mentor, or just look in the pop-up menu on the new ticket page yourself.
Generally, you should follow the same instructions for ReportingBugs and RequestingFeatures as our users are supposed to. That includes searching for duplicates, and learning and using WikiFormatting.
Close tickets with your commits
If you say “fixes #nnnn” or “closes #nnnn” in your commit message, Trac will notice and close the relevant ticket.
Of course, it's case-insensitive, and you can close as many tickets as you need to this way.
Comment on tickets with your commits
If your commit is relevant to a ticket, but won't completely resolve it, then you can simply say “references #nnnn” (or “refs #nnnn” for short) in your commit message. Again, Trac will notice, and it will post your commit message as a comment on the relevant ticket.
Just like “fixes”, it's case-insensitive, and you can comment on as many tickets as you need to this way.
Delete with confidence
As long as the code you don't want anymore has been committed, you can delete it freely. Don't just comment it out or #if 0 it out—delete it. It can always be brought back with svn merge if it's needed again.
Don't use the -m switch
The svn ci (or svn commit) command takes a -m switch that accepts the commit message on the command line.
Don't use it.
Shell escaping
The problem with -m is that the shell demands \-escaping in order to pass various punctuation characters, such as ", ', and !, on to svn. If you do it wrong (which is very easy), you end up with \ characters in your commit message. This is harmless, but ugly.
Immediacy
If you use -m, your commit will happen now. That sounds like a good thing, but it's not: You may have caught files in a broad commit that you didn't actually want to commit yet, or omitted files because you forgot to add them first. -m doesn't afford you any opportunity to back out upon noticing that.
Excess brevity
It's really hard to do a multi-line commit message with -m; it basically requires serious shell acrobatics to get the newlines passed to svn.
Multi-line commit messages are generally a Good Thing, as they let you more expressively describe exactly what you're doing. -m does a really good job of impeding this expressiveness.
The solution
Leave -m out, and use your EDITOR to write your commit message.
Setting up you the EDITOR
The default EDITOR is vi. If your vi-fu is not strong, you can use another editor instead. In Bourne-like shells (sh, bash, zsh, ksh), type this:
export EDITOR='blaaaah'
In csh-like shells (csh, tcsh, zsh with certain options), type this:
setenv EDITOR 'blaaaah'
You will then have to add this same line to a certain file in your home directory. In bash, use .profile. In zsh, use .zshenv.
Using your EDITOR to write the commit message
When you start the commit, svn will invoke $EDITOR as a subprocess. Write your commit message in the editor, then save and quit.
Some GUI editors, like TextWrangler and SubEthaEdit, provide command-line tools that have a -w switch. With the -w switch, the command-line tool will not exit (that is, it will wait) until you have saved and closed the document in the GUI editor. (You don't need to quit the GUI editor.) If you set EDITOR to such a command (for example, EDITOR='see -w'), you can use that GUI editor for things like svn.
We know that building takes a long time on some systems. Fortunately, you have a multi-tasking operating system. Start the build, then type svn ci command into the Terminal and write your commit message in the editor. If the build finishes successfully, you can then save and close/exit the editor and svn will go through with committing your known-building source. If it doesn't, you can fix the problem, then commit.
Aborting the commit
Perhaps you can't commit it just yet. Maybe the work required to fix it should instead be broken up over multiple commits. In this case, you'll want to abort the commit.
First, you probably want to save your commit message. Save it to another file; don't save it to svn's temporary file, or it will think you want to commit now using that message. (If you already saved to the temporary file, delete everything, then save to the temporary file, then undo.) In vim, use :saveas Filename.commit; in a GUI editor, use the Save As command.
Then exit the editor. In vim, use :q; in a GUI editor, just close the document.
Once the editor (or CLI tool, in the case of a GUI editor) has exited, svn will examine the file. If you did it right, the file doesn't contain a commit message, so svn will ask you whether you want to abort the commit, commit it with an empty message, or re-edit the commit message. Choose abort. Now you can go fix the code, or svn revert it if you want to completely abandon that direction. (Warning: svn revert is NOT undoable.)
