With the switch from CVS to subversion as a source code revision control system for Asterisk, a lot of new possibilities was created. One of them was branching. A branch is a copy of a repository where a developer or a team of developers can add new code without affecting the main version of the source. The extra benefit is that a branch maintains a relationship with the main source code. When new features are introduced or bugs fixed in the main source code, the changes are easily imported into the branch. When the development in the branch is done, the resulting changes can easily be merged into the main source code.

In Asterisk, both developers and bug marshals have the right to create branches. Bug marshals will open a branch if someone contributes a large enough patch that needs peer review and testing. In order to keep the patch up to date with the changes in the main source code, the subversion trunk, a bug marshal opens up a branch, patches it with the patch and makes sure that it is kept up to date. This makes it easier for people that want to test a patch and developers that contribute patches.

What is in a branch?

Most of the Asterisk branches contain all of the Asterisk source code from the trunk, the development version of Asterisk. When creating a branch, you copy a revision of the subversion repository. A copy can be made from an old revision, or the current revision, from the development branch or the release branch (currently 1.2). When you check out a branch, you will get a complete Asterisk to build on your system.

How do I check out a branch?

You need to install subversion. It’s available on most Linux distributions, as well as in Darwin ports for OS/X and in the ports for FreeBSD. The executable binary for subversion is named svn. In subversion, everything is a URL. Subversion, being developed by the Apache Software Foundation, is based on WebDAV, the distributed authoring and versioning system for HTTP. All branches are in the /svn/asterisk/team directory in the subversion server at svn.digium.com.

You can view the available branches at svn.digium.com/view/asterisk/team. Some of these are just playgrounds for new ideas, but some are patches from the bug tracker, or features that has an open report in the bug tracker where the developer asks for peer review. You are free to download anything you want, but there is no guarantee that it works or does anything useful unless the maintainer of the branch has told you so.

In order to check out (that’s the terminology for downloading) a branch, you first select the name of the branch you want to test. For my multiparking patch, the name is multiparking in the oej directory. The URL for that is http://svn.digium.com/view/asterisk/team/oej/multiparking if you want to view the source code and look at changes and comments I’ve made while adding new code. To check out, you use http://svn.digium.com/svn/asterisk/team/oej/multiparking. Notice the difference? In the first case, the url contained the view key word, in the second case, it was replaced by svn.

The command line for checking out multiparking into a directory named multiparking looks like this:

svn checkout http://svn.digium.com/svn/asterisk/team/oej/multiparking multiparking

This command will create a directory named “multiparking” in the directory you issue the command. That directory now contains all the source code you need to test this module. Just enter it and compile and install as usual.

How do I see what’s different?

If you want to compare a branch with the trunk, or create a diff file for integrating several branches and patches into one common source code tree, you can use subversion to show you the difference between a branch and the trunk.

svn diff http://svn.digium.com/svn/asterisk/trunk http://svn.digium.com/svn/asterisk/team/oej/multiparking

This command will show you the difference between the trunk and the multiparking module. If you take the output of this and save it into a file, you have a patch file that you can apply. svn contains a lot of help texts. svn help is a good start.

Any more questions?

If you have any more questions and want to learn subversion, there’s a free book called Version control with subversion freely available on the net, as well as in hardcover in book stores. If you have questions on how to checkout or work with Asterisk in our repository, use the mailing lists for asking, or find developers in the #asterisk-dev IRC channel on freenode.

Now, please go downloading and start testing! Help us developing a new generation of Asterisk!