The latest code for all our projects is in an open source version control system called SVN (SubVersioN). Download and install a program like TortoiseSVN (Windows) or RapidSVN (multi-platform GUI - requires Subversion) to access the SVN repository.
For a complete description of SVN, see the free book.
Checking out code
How to use TortoiseSVN to check out the development source code on Windows:
- Right click->SVN checkout on your desktop or Windows file explorer.
- Enter the SVN address (http://dangerous-prototypes-open-hardware.googlecode.com/svn/trunk/) and a directory to use. Choose anonymous check out.
- If you have commit permissions (you've been added as a developer on the project), then use the secure SVN address (https://dangerous-prototypes-open-hardware.googlecode.com/svn/trunk/). Give Tortoise your email address when prompted. Your Google SVN password is different than your account password - get your Google SVN password here.
- TortoiseSVN will download the source.
Checking in code
The developers work in the TRUNK folder. Please always enter a short log message when you commit code. Live commit logs are available on the developers mailing list.
If you're contributing to the project:
- Make your changes
- Right click on the modified file and choose SVN commit
If you added new files to the project:
- Right click the file and choose SVN->add
- Right click the file and choose SVN commit
TortoiseSVN – Basic Usage
TortoiseSVN integrates into the Windows shell. Tortoise provides a nice UI over the svn console package, which can be used from the command line via the svn command.
Tortoise provides color-coded icon overlays that show the status of files, the most commonly seen are circled.
Files and folders can have a few states: non-versioned, up-to-date, or locally modified. When a file is initially created, it is non-versioned, to get it into the repository simply right click, and select TortoiseSVN-->Add…
You can then right click and select “Commit” to permanently add the file to the repository.
Each time you perform a commit, it is a VERY good idea to add a comment and explain what you’re changing. This makes looking back through logs much easier. In the case of community-driven projects, such as Dangerous Prototype projects - other developers can keep abreast of what the new developments are simply by browsing the svn email distro (but only if the commit messages are detailed enough).
After each commit, you’ll see some status messages. If there’s any RED, you have a problem.
In order to make sure you have the most up-to-date copy of a file, perform an “update”. This will automatically download the latest version of files, as long as you don’t have any local modifications to the file.
TortoiseSVN – Neat Features
SVN information in “detailed view”
Sometimes its useful to see revisions, status, etc, this can be done by adding some custom columns to your detailed view. This is sometimes useful when using more advanced techniques such as switching between trunk, tags, and branches.
You'll then see the additional information from SVN
Subversion Project Structure
Note: we don't actually do this, but we should...
Subversion has no notion of a project or module, it simply tracks changes to a file system. However, there are a series of conventions that can help us keep track of things better. The software repository will be organized with a series of top-level “projects”. Each “project” will be a distinguishable piece of software, such as [bus pirate firmware?].
Each project contains 3 subdirectories: branches, tags, and trunk.
The trunk directory traditionally contains the latest main line code.
This directory contains snapshots of selected (or all) files in the trunk that users wanted to save for some reason (a test build, or a checkpoint after some feature started working). Once created, these snapshots should not ever change; otherwise, the tag doesn’t have much meaning!
Contains a branch of development. Hearing terms such as maintenance and feature branches are common. Let’s take a maintenance branch as an example. We release [bus pirate 1.0.0], we’ll create a tag of the trunk named [bus pirate 1.0.0] (this will show up in the tags folder as a copy of the trunk the moment it was tagged). We’ll also create a branch, which shows up in the branches folder as a copy of the trunk the moment it was branched.
We are in the middle of coding v 1.1.0 on the trunk- adding support for a new instrument, the communications library is receiving a major overhaul to be more efficient, etc – things are in flux….majorly. Now the service department frantically discovers they need a check box tweaked because customers are confused. Changes don’t need to be applied to the trunk, we can go in and make changes to the 1.0.0 branch, compile, test (possibly running regression tests as well) and release 1.0.1, all while not touching the unstable code that will be 1.1.0. All changes were isolated to the branch.
Now, two months later, we’re ready to release v 1.1.0, but we want all the bug fixes that have accumulated through version 1.0.8. We can merge the changes (in a fairly automated fashion) from the 1.0.0 branch back into the trunk using diff tools which highlight differences between the files and semi-intelligently apply changes – with developer’s guidance, of course. After the merge, we’re ready to compile and test the release. In practice, it’s a good idea to do merges on a fairly regular basis to prevent things from getting too dissimilar if changes are happening rapidly.