Hi everyone!
As we roll towards this year’s competition, I wanted to suggest something for the volunteers who will be working with control systems programmers (and the teams who have control systems programmers, and the team members who are control systems programmers… Hello, my fellow code-slingers!). If you’re already familiar with version control, feel free to skip all of this. Executive summary:
- version control is a good thing
- I recommend git for teams because it doesn’t require the internet
- I’ve provided some links at the bottom to tools that make git easier to use
Before I dive any deeper into this, I should direct you to the excellent document put together last year by Austin Wright (team 498 alumnus). Document hosted on Google Docs. He already said many things about git that I was going to say, and several of them better; consider this message a refresher on the ideas and an update on some new developments in version control.
Why use version control?
One of the big things I learned about in college that I wish I had known in high school was version control. I remember that when I was working on my team’s robot control code, we would sometimes need to make very quick, experimental changes under a tight deadline. We ended up with dozens of little folders labeled “control system_1”, “control system_2”, etc. It was a disorganized mess; code could get saved in the wrong folder, they would get lost (put on the wrong floppy disk), etc. It’s a pattern I’ve seen repeated with many teams over the years.
Version control software is basically a system to manage the problem of code changing over time. Instead of backing up versions of the code to other folders, you register files with the version control program (VC) and when you want to make a “backup”[1] (checkpoint), just tell the VC to make it. The VC will keep the checkpoint and a log of what was changed, and if you ever need to pull up a backup and use it, you can just say “Give me the code from Monday” or “Give me version 2”. There’s always a “right way” to do save-this-version-so-I-can-get-back-to-it-later, and nothing can ever get lost.
Checkpointing is the main thing a VC does, but the metaphor goes beyond recording the past. VC software also lets you make “branches,” which are like specialized versions of your code to test experimental ideas or for one programmer to make detailed, finicky changes without interfering with the rest of the team. A successful branch can be merged back into the project (becoming part of the regular code), or kept around as a separate part for special purposes. For example, a team might have an automation feature they don’t fully trust; they can keep it on a branch, and if it turns out to not be useful they can just switch back to the regular behavior by moving from the branch to the main code history without losing anything.
There are several VC programs available, the most popular probably being subversion (http://subversion.tigris.org/). I use subversion (svn) regularly, and it’s a great tool. However, it requires the computer to be able to access a subversion server, which may not always be possible for teams that lack a reliable internet connection. Another VC that may serve the needs of FIRST teams better is called git (http://git-scm.com/). Git acts as a more decentralized VC; with a VC like subversion, the server maintains the “repository” (the binary-soup of files that make up the entire history of the project and allow you to pull up any checkpoint that has been made). If you can’t access the repository, you can’t make a new checkpoint or move to another checkpoint. With git, each individual machine using a project keeps a copy of the project’s whole history, so each machine is both a client and a server. Teams can use a centralized server, but they can also do something more “sloppy” like keep the repository on a few loosely-affiliated laptops or desktop machines, synchronizing their histories when it is convenient to do so.
Tips on using git (and version control in general)
Commit early, commit often
One significant difference between version control and keeping a loose bag of backup folders is that is is much cheaper to make a checkpoint (also known as a “commit”) than to copy a project. Much cheaper, both in space used and time used. I try to commit every time I add a new feature, no matter how few files or lines I changed. That makes it easier to roll tiny pieces of the project back if I made a mistake.
Branches are cheap (in git)
The way git is designed, branching (and merging branches back into the main code body) is very easy; it’s assumed every programmer has his or her own personal branch. So make branches whenever you want to experiment with an idea that is in the least bit “risky.” You can always back up if you find it’s not worth the time to chase the idea, and you won’t lose the work you put into it already.
It’s not just for robot code
Does your team do its own promotional materials? Version-control the flyers and announcements. Does the team keep a team contact sheet or roster? Version-control it so you can remember who was on the team in 2009 when you’re doing your five-year anniversary montage in 2014. Does the team have a website? Most definitely version-control that. You can have as many or as few repositories as you want; any file that changes over time could likely benefit from being version-controlled.
It’s not actually a backup
This is an important point to keep in mind: version control isn’t quite the same thing as backing up unless a copy of your repository lives on another computer (such as the GitHub service; see GitHub in “Tools to use with git,” below). Version control basically adds a rewindable history to each file in the form of the repository; while it can be used to fix a file that is damaged, damage to the repository itself will ruin the history. You’ll still need to be able to restore the entire repository from an off-computer backup if you accidentally set your machine on fire[2].
Tools to use with git
documentation
Most of what I know about using git came from one document: the “Pro Git” book (http://progit.org/book/). This is fairly comprehensive and covers more-or-less everything important in a pretty straightforward manner.
user interface
By default, the user interface to git is command-line only: you tell git what to do by invoking commands like “git init”, “git add”, and “git push”. But there are a couple of great GUI tools to simplify that process.
- tortoisegit (http://code.google.com/p/tortoisegit/) This is the VC I use. I believe it is Windows-only, but it works extremely well. It acts as an extension to Explorer; when you right-click on a file or directory, one of your Windows submenus will be a “git” submenu that lets you perform operations on the given context. I find this to be more convenient than the command-line tool a lot of the time, but it is Windows-only.
- SmartGit (http://www.syntevo.com/smartgit/index.html) I just started playing with this one. It’s a Java-based GUI tool, so it will work on both Windows and Macintosh computers (I have only tried it on Windows). It’s brand-new, but it seems pretty solid. They have a commercial license for it, but you can download it, install it, and use the free license for the FIRST competition.
hosting
Even though git works perfectly fine without an external server, a centralized server can be useful for collaboration. If a team wishes to, they can certainly set up a machine owned by them to be a central server; however, there is an option for creating a host on the web that can be accessed anywhere in the world with an internet connection.
- GitHub (http://github.com/) The most well-known public git repository host. They provide private hosting for a monthly fee, but their most commonly-used service is free public hosting. It’s not hard to set up, and it also comes with a bug tracker and a wiki (useful for documentation) with every repository. Note that the “public” in public hosting means that anyone in the world can see and download the data you push to github (although only the team members could do the uploading). I personally find this sort of code-sharing and code re-use to be very much in the spirit of FIRST, but it’s something to keep in mind if your team doesn’t feel comfortable having their algorithms exposed for the world to explore.
Conclusion
- Version control saves hair-pulling frustration. Teams perform better when they aren’t worried about their appearance. Save your hair; use version control.
- The internet can be hard to find. Git doesn’t require the internet. Use git.
Notes
[1] Checkpoints aren’t exactly like backups; see the “it’s not actually a backup” tip
[2] That happened to me once. If you turn on a computer and it starts clicking instead of booting up, try not to be surprised when after turning it off and on again it lets out the magic smoke.
