The AccuRev CLI – Going beyond SCM

October 1, 2008

By Ryan LaNeve, AVI-SPL

Much has been written on this blog already regarding the ease with which AccuRev allows you to tailor your development process without having to fight with your SCM software. While I could offer yet another account of how simple and straightforward it is to manage our particular process using AccuRev, instead I thought I’d take a few minutes to point out some of the things we’ve done using the tool’s command-line interface and its ability to output results formatted as XML.

Of the various tools we have created over the years, the two we find most useful are what we call “AccuLoad” and “SQL Object Scripter”. The former pulls data out of AccuRev, while the latter puts data into AccuRev. Both were developed in a matter of hours thanks to the extremely intuitive command-line interface which AccuRev provides. Let’s take a closer look at each.

We’ll start with our “SQL Object Scripter”. Anyone whose development efforts involve a database server knows how difficult it is to maintain change logs for the “code” kept within the database. There are a number of “best practices” with regards to maintaining this information within an SCM, but in our experience they are all too time-consuming and involved, which leads to one or more members of the team either forgoing the process due to time constraints or just ignoring the process all together. Maybe we’ve just become spoiled by AccuRev allowing us to work exactly the way we want and otherwise staying out of our way, but we now have a hard time following any procedure which requires us to change the way we do things.

So one day a couple of us sat down and decided to find a new solution. We felt that, at a minimum, what we really wanted was to be able to view changes over time for our database objects, such as tables, views and stored procedures. We knew that if we could just get each change into AccuRev some of our issues would immediately disappear, but we found it too difficult to require the entire team to manually create every script and then manually promote that script into our SCM. We decided that what we needed was a tool that could simply detect changes to our database objects and automatically store those changes within AccuRev. Again, thanks to the simplicity of AccuRev and its CLI, our “SQL Object Scripter” tool was born in a matter of hours. We now have a record in AccuRev of (almost) every change made to any database object we care about, which then allows to use the features of AccuRev to view the history of any object, the differences between any versions of any object and even an annotation of any object to see who is responsible for the make-up of the object. The solution consists of a few parts: a SQL Server table to store DDL change event details, with a DDL trigger on the various databases we care about. The trigger fires whenever a DDL event occurs, such as the creation or alteration of a table, view or stored procedure, and the details of the event get logged to a table. Our custom console app is then scheduled to run every few minutes and checks the table for any records. When a record is found, the console app scripts out the definition of the object to a file and then uses the AccuRev CLI to add/keep/promote the file to our “SQL Scripts” depot – whatever is appropriate depending on whether the object is brand new or pre-existing and has been changed. The AccuRev commands all run within the context of whichever user made the change in the database itself, so all of our AccuRev transactions are associated with the correct team member. While this solution is not optimal and does not provide as much traceability as having each developer maintain and promote database change scripts themselves, we have found it to be an excellent interim solution which was extremely easy to put together.

Another of our tools is the one we call “AccuLoad”. The purpose of this tool is to pull various bits of information out of AccuRev and load that information into a database. We then use the information in the database from several other applications. The tool is a console application which runs in a couple of different modes, but the primary mode is run via an AccuRev trigger. Whenever a promote happens in one of our depots, our custom trigger runs and fires up our console app, passing in a few details such as the name of the depot, the name of the stream and the transaction number of the promote. AccuLoad then takes this information and makes various calls to the AccuRev CLI to gather more details, such as which elements were included in the promote, the version numbers of each of those elements, the user who performed the promote, etc, etc… Additionally, a diff is run against any changed elements, and those details are stored in the database as well. Gathering all of this information from AccuRev was extremely simple thanks not only to the intuitive nature of the functionality exposed by the AccuRev CLI, but also thanks to the option of having the results returned as XML. While I’m sure it would have been possible to create such a tool using any SCM, I doubt we would have ever found the time to do so had we not been fortunate enough to have AccuRev as our SCM. It was, again, only a matter of hours from the time we came up with the idea for AccuLoad and the time our first promotions were being logged in our database.

Having this database detailing the activity in our SCM, we were then able to create several other tools to utilize the information, such as one we call “AccuBrowse”, seen below. This web-based application allows us to browse the database and view any transaction within any stream of any of our depots, and see who performed the promote, the comments supplied during the promote, the elements included in the promote and the differences for any changed element. I should mention that much of this functionality is probably available in the AccuRev Web Interface, though we have not actually used that tool provided by AccuRev. Ours was created a couple of years ago and suits our needs. Beyond just allowing us to browse our SCM history via a web-interface, our database also allows us to perform some analysis, such as frequency of change for elements within a specific depot or stream, which allows to keep tabs on classes within our systems which may have too much responsibility. We can even run queries against the data to find “problematic” code, such as those files most often included in promotions which cause a failed build (not that our builds ever fail, of course…).

In summary, there are a myriad of fantastic features and functionality within AccuRev which make it a great fit as an SCM for any development environment. Once you’ve got your core needs taken care of by the out-of-the-box functionality, I encourage you to explore what can be done with the provided CLI and its XML-formatted output. In our experience, if you can imagine it, you can build it with AccuRev in no time at all.

Our custom AccuBrowse application, viewing a transaction involving a SQL Server stored procedure:


Build your own custom interface to AccuRev issue tracking

January 30, 2008

If I had to guess, I’d say that roughly one third of our customers are using AccuRev’s built-in issue tracking system, called AccuWork. Another third are using one of any number of 3rd party systems, and the last third aren’t linking to issue tracking at all. Those not using issue tracking I feel are missing out on one of the key advantages of software development using an Enterprise class SCM system like AccuRev, but that’s a post for another day. And those using a third party system have that tool’s interface to work with if they want to set up any customizations. So I want to focus on the group using AccuWork.

What many people aren’t aware of is that not only does AccuRev have a full featured command-line interface for SCM operations, it also has CLI operations for the issue tracking as well. Additionally, it has the flexibility of using XML and all the inherent benefits of that language. So an example of what some organizations might want to do is set up an intranet web page where various, non-SCM users can submit issue records without having to go through a specific client application. This can be a very straightforward effort using the AccuWork CLI.

Step one would be to design your web page and forms. Simple for any experienced web developer. Any desired validations and logic would be built into this web page. Step two is to merely grab the form data, translate it into the appropriate XML format, and submit it to AccuRev. Here is a sample xml structure to create an AccuWork issue record (your schema may vary):

<newIssue issueDB="Support">
    <status fid="3">New</status>
    <shortDescription fid="4">We want to have another issue</shortDescription>
    <productType fid="6">Receiver</productType>
    <type fid="7">enhancement</type>
    <submittedBy fid="10">3</submittedBy>
    <assignedTo fid="14">1</assignedTo>
    <foundInRelease fid="20">TP_3.5</foundInRelease>
    <dateSubmitted fid="11">1083606275</dateSubmitted>

Lastly, you would send this xml to AccuRev using the standard CLI:

“accurev xml -l issueFromWeb.xml”

Bingo, you now have an AccuWork record created! That’s a basic example, but since AccuRev also gives you the ability to query issues and modify existing issues via XML CLI, you can start to imagine the flexibility you have for customization and specialty access.

I’m interested in hearing from development organizations about their issue tracking usage. Do you typically have a wider audience for the issue tracking side than the actual coding side? Does the previous information sound like it’s something you could make use of?