First, thanks to all of the folks who wrote in with suggestions for Under the Hood topics. Keep them coming! One of those suggestions, and something that we get frequent questions about in technical support, was a request for a guided tour through source control integration into FogBugz.
The goal of this installment of Under the Hood is to give you a foundation in the interaction between any source control system and FogBugz. You will learn:
- What information FogBugz needs to be given with each commit
- How FogBugz processes that information
- How FogBugz displays that information and links back to your source control system.
In order to make this less abstract, we will use FogCreek's own configuration, with Subversion, as an example.
The end goal of the integration process is to get FogBugz to display all of the commits related to a particular case in the bug interface.
By looking at this, we know that FogBugz displays specific information about each commit associated with this bug. It shows us the revision number from the source control system and the filename, including the path. Just beneath the surface it is also tracking the previous revision number so that it can link back to your source control system to show you what has changed since the last time this file was modified (also known as a diff). From this, we can deduce that the four key pieces of information are file name, current revision, previous revision, and BugID. The question is, how do we get this information to FogBugz?
In order for any integration to work, you need to tell your source control system which case number is associated with a particular checkin. In our example, this information is included in the comment required by each checkin. We use the key word "BugzId" right before each case number so that we can look for it later when Subversion executes our post-commit hook.
Note: A post-commit hook is a mechanism built in to Subversion which allows you to create a shell script that will be executed immediately after a commit is completed (most source control systems provide something similar).
In this case, our post-commit hook causes Subversion to create a log file of the commit with information about each file committed, the revision numbers, and to which bug that checkin is related. Then, we parse the log file and scrape out the key information that we identified above.
Note: The post-commit script creates the log file, and passes it to the logBugDataSVN script which parses it and processes the web requests. You can find both of these files in your FogBugz\accessories\SourceControl\Subversion directory
For each of the BugzIds that we find in the log file, we build a programmatic request to the cvsSubmit.asp page in our FogBugz installation. When completed, the request for the first file in our example looks like this:
http://your.fogbugz.com/fogbugz/cvsSubmit.asp?ixBug=19&sFile=trunk/website/default.asp&sPrev=0&sNew=5
Note: Subversion doesn't require the previous version number to display the diffs, so we pass it a 0 for sPrev. Also, this URL works just as well typed in the address bar of your browser as it does being created and called programmatically.
Assuming we get a valid response from the FogBugz web server, we move on to the next file name or BugzId in the log file. The remainder of the processing is done by cvsSubmit. It takes each of the parameters we pass to it, and inserts it into the appropriate fields in the CVS table of the FogBugz database. If you look at the schema, you will see that there is a field that corresponds by name to each of the parameters from the URL above.
The last thing that FogBugz needs to do is display this information in a useful way when you view a bug that has checkins associated with it. You will notice that in the screen shot, both the file name and the revision number are active links. For this to work, the source control system with which you are integrating must have a web interface. The first link, from the filename, sends you to the log of activity associated with that particular file. The second, from the revision number, sends you to a diff between that revision number and the previous one stored in your source control system. To generate these links correctly, FogBugz needs to be told how to format them. This configuration is controlled by the "Source Control URL for logs" and "Source Control URL for diffs" properties on the Site configuration page within FogBugz.
Below each property, you will see examples of URLs for all of the supported source control systems. In our example, we are using WebSVN, so the example URLs are:
Each of the URLs contains variables that FogBugz will replace with the correct value from the CVS table when it renders the bug information. For the first file in our example,
^FILE = trunk/website/default.asp
^R1 = 0
^R2 = 5
The URLs for this checkin are:
If you had a source control system that required a different format for these URLs, you would replace them on the Site page and use the ^FILE, ^R1, and ^R2 variables where needed. Finally, FogBugz repeats this process for each of the files it finds in the CVS table associated with this bug, and displays them as the list under the heading of "Checkins".
With this information, it should be possible to integrate nearly any source control system into FogBugz. If you want to see more detail about Subversion integration, take a look at ourKnowledge Base article on Subversion Integration. As always, if you have any questions or comments, please don't hesitate to contact us. And keep those suggestions for future articles coming!
