***** Basic Information ***** SVNTurmoil Created by students of the University of Idaho Computer Science 481: Senior Capstone Sponsor: Hewlett-Packard Company Contact: Bruce Mayes Supervisor: William Junk Fall 2007: Team 49 http://www2.cs.uidaho.edu/~cs481-49 Spring 2008: Team 53 http://www2.cs.uidaho.edu/~cs481-53 ***** Licensing ***** Copyright (c) 2008, Hewlett-Packard Company and the University of Idaho All rights reserved. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: * Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. * Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. * Neither the names of Hewlett-Packard, University of Idaho, nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. ***** What is turmoil? ***** Code turmoil is a measure of change in code. This metric is formed by counting the number of lines added, removed or changed during development. ***** What is it used for? ***** There are many uses for code turmoil. One use is to educate developers. Every time a developer submits a change to the code, turmoil is reported to them. Often times it is a shock to see just how much change they have introduced. Another use for turmoil is as a sanity check. When a developer submits a change, they can see the amount of turmoil they have introduced. They may say that the turmoil is about right, or they may find that the turmoil is way too high or too low and review what they have submitted. A third use is project management. As a project approaches release the amount of turmoil should decrease. This indicates that the project is being polished and not undergoing major construction. If there is a sudden spike it may indicate that a postponement is required. Lastly, since the tool already counts lines of code, it was a simple thing to add a feature that reports code size, although not directly related to turmoil. ***** How to use SVNTurmoil ***** No installation is necessary to use SVNTurmoil. It is a Perl script so all that is needed is a Perl interpreter and Cygwin (for some external tools). It may be necessary to tell SVNTurmoil where some programs external to SVNTurmoil are on your computer. This document does not address this topic. See the Operational Specification. SVNTurmoil is strictly a console based program. This means that on Windows, a "cmnd" window needs to be open. On Macintosh or Linux based systems a terminal needs to be opened. There are a number of actions possible with SVNTurmoil. To highlight a few of them the following four sample calls have been provided. This is by no means an in depth discussion of each option and case. See the Operational Specification. To measure turmoil on a remote repository with itemized output: > perl SVNTurmoil.pl -p MyProgram -o http://www.myrepository.com/root/@1 -r http://www.myrepository.com/root/@2 To measure turmoil on a local repository with itemized output: > perl SVNTurmoil.pl -p MyProgram -o C:/LocalCopy1@1 -r C:/LocalCopy2@2 To measure turmoil on a local repository with categorized output: > perl SVNTurmoil.pl -p MyProgram -o C:/LocalCopy1@1 -r C:/LocalCopy2@2 --use-case cat To obtain a size measurement on a local repository: > perl SVNTurmoil.pl -p MyProgram -o C:/LocalCopy1@1 -r C:/LocalCopy2@2 --use-case size ***** How to interpret the output ***** When SVNTurmoil is executed there are several output files. .filelist This contains a list of each file in the repository to be measured. In some cases this file is user supplied and in some cases this file is automatically generated. .filelist-ignore This contains a list of files that do not need to be measured in the .filelist file. In some cases this file is user supplied and in some cases this file is automatically generated. .raw This contains the raw turmoil numbers for each file in the .filelist file and NOT in the .filelist-ignore file. .raw-ignore Even files are "ignored" their turmoil is still calculated for those files. That information is found in this file. Should it be found that some files were erroneously "ignored", the entire repository does not need to be measured again. .tbl T.B.L. stands for "Turmoil Between Labels". When a major build is run, the itemized outputs can be ponderously large. This categorized output summarizes that data. .log During an execution of SVNTurmoil there are many opportunities for errors. If an error occurs this file will give debugging information. ***** Caveats ***** Please note that performance is dependent on the external tools in use. For example, the Windows version of Subversion (SVN) may output files with directories using backslashes instead of the forward slashes as found on Cygwin Subversion. Another good trick is line endings. Windows insists on using "Carriage Return - Line Feed" at the end of each line while Linux and Macintosh use "New Line". Although SVNTurmoil attempts to minimize these differences as much as possible, be aware that they do exist. Even changing versions of your tools may cause changes that were not anticipated nor tested for in SVNTurmoil. Furthermore, Cygwin diff may measure differences between files differently than other versions of the diff tool. This could cause differences in the measurments taken. Be aware of this and try to be consistent in which external tools you use. If executing on Linux/Mac and Windows, Cygwin diff will be most similar to the diff tool found natively on Linux/Mac. ***** Resources ***** With all that said, good luck and happy hunting. For further information visit http://www2.cs.uidaho.edu/~cs481-53. In particular if you have any questions see "Documents" for the Operational Specification and Design Specification.