1.1. Copyright Information

This document is copyright (C) 2004 by the various Scmbug contributors who wrote it. It is licensed under the GNU Free Documentation License.

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts, and with no Back-Cover Texts. A copy of the license is included in Appendix B.

Scmbug is free software, licensed under the GNU General Public License.

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.

1.2. Disclaimer

No liability for the contents of this document can be accepted. Follow the instructions herein at your own risk.

1.3. Acknowledgments

The excellent Bugzilla Guide served as an example in preparation of this document. Content and structural document elements were reused from this guide. The LDP Author Guide also served as a good example.

Development of this system benefited from invaluable insight on SCM and bug-tracking issues, along with feedback, from John C. Quillan, Mark S. Reibert, Dave Swegen, the Bugzilla developers, and the Subversion developers.

1.4. Document Conventions

This document uses the following conventions:

Descriptions	Appearance
Warning	Don't run with scissors!
Hint	Would you like a breath mint?
Note	Dear John...
Information requiring special attention	Read this or the cat gets it.
File or directory name	filename
Command to be typed	command
Application name	application
Normal user's prompt under bash shell	bash$
Root user's prompt under bash shell	bash#
Environment variables	VARIABLE
Term found in the glossary	cvs2cl
Code example	<para> Beginning and end of paragraph </para>

This documentation is maintained in DocBook 4.2 SGML format.

2.1. What Is It?

Scmbug is a system that integrates software configuration management with bug-tracking. It is implemented in Perl and has been successfully deployed on UNIX-like and Windows systems. It is pronounced Scum-bag.

2.2. Why Use An SCM System?

Those who do not use a software configuration management (SCM) system do not maintain a history of modifications performed to their software. When bugs creep in their software, they do not have adequate information on how changes to source code came about.

SCM systems, or even simple source code version control systems, make sure that a record of all changes and enhancements to the software is maintained. They provide a method of creating, storing, and labeling software changes.

2.3. Why Use A Bug-tracking System?

Those who do not use a bug-tracking system tend to rely on shared lists, email, spreadsheets and/or Post-It notes to monitor the status of defects. This procedure is usually error-prone and tends to cause those bugs judged least significant by developers to be dropped or ignored.

Integrated defect-tracking systems make sure that nothing gets swept under the carpet; they provide a method of creating, storing, arranging and processing defect reports and enhancement requests.

2.4. Why Integrate SCM With Bug-tracking?

SCM systems maintain software changes. Bug-tracking systems maintain lists of software enhancements and defects. By examining a log of software changes, it is uncertain why the changes occurred. By examining a log of defect reports, it is uncertain what changed in software in response to the defects.

Integration of SCM with bug-tracking ties the reason why a feature/defect was developed/fixed with what software changes occurred in the SCM system to accomplish this.

3.1. Goals

The goals of Scmbug are:

• Provide synchronous verification checks of SCM actions against the bug-tracking system.

• Provide a flexible architecture that can be deployed across the public Internet with reasonable security. Permit integrating repositories hosted by multiple SCM systems in separate networks, against a single, publicly accessible bug-tracking system, for use with multiple mobile developers.

• Define an SCM to bug-tracking integration interface and mechanism that will permit integration of any SCM system with any bug-tracking system.

• Encourage developers of other SCM to bug-tracking integration efforts to solve the integration problem once and for all.

• Integrate most popular free SCM or source code version control systems, such as CVS, Subversion, and Arch.

• Integrate most popular free bug-tracking systems, such as Bugzilla and Mantis.

3.2. System Architecture

Scmbug is developed as a client/server solution. As shown in Figure 3-1, it consists of a set of SCM system hooks that capture standard SCM events, a generic mechanism of handling these events on the machine hosting an SCM repository, a server daemon onto which integration requests corresponding to these events are transported, a generic mechanism of handling these requests, and functionality that can process these requests per bug-tracking system.

When various SCM events occur, such as committing software changes or labeling a repository, they are captured using hooks installed by Scmbug. Before the event's activity is allowed to proceed, various verification checks are performed as described in Section 4.2. These checks are synchronous; when an error is detected, the event's activity is stopped.

3.3. Related Systems

Scmbug is not original work. Most of the integration features separating it from related systems were first conceived and implemented by John C. Quillan for CVS and Bugzilla. The distinguishing features of his work are the synchronous nature of the verification checks, and a VDD Generator tool similar to the one described in Section 7.2. His work was never publicly released. Scmbug attempts to continue a redesigned, clean-room implementation of that work, supporting a wider variety of SCM and bug-tracking systems.

Other systems that integrate SCM with bug-tracking are described below. Along with Quillan's work, these solutions are unsuitable for certain development environments.

4.1. Integration Actions

For every SCM event, multiple corresponding integration actions may be issued from the glue to the daemon. The list of possible integration actions is:

• activity_verify: An activity_commit integration action will soon follow, and data collected from the corresponding SCM event must be verified first.

• activity_commit: A software change has already been committed in the SCM system, and this event must be integrated with bug-tracking. This action usually follows an activity_verify integration action.

• activity_tag: A software labeling operation is issued in the SCM system, and this event must be integrated with bug-tracking.

• activity_get_vdd: A VDD will be produced by the VDD Generator.

4.2. Verification Checks

When various SCM events occur, verification checks are performed before the SCM event is allowed to proceed. Some checks are performed by the glue on the client side, the machine the SCM repository resides. Other checks are performed on the server side, the machine hosting the Scmbug daemon.

#
# Flags whether the glue is active
#
enabled => 1,
	      

# Comma(,)-separated list of paths to any binaries the SCM
# tool may need to use
binary_paths => '/usr/local/bin,/usr/bin,/bin',
	      

log_template =>  {
    # The bugid_regex is a regular expression that must set
    # the unnamed variable $1 to the bug number, or list of
    # bug numbers. It is checked for a match as: m/$regex/s
    bugid_regex => 'bug\s*(.*?):',
    # The bugid_split_regex is a regular expression describing
    # how a list of bug ids will be split in individual bug
    # numbers. It is split as: /$regex/
    bugid_split_regex => ',\s?#|\s?#|,|\s+',
    # The log_regex is a regular expression that must set the
    # unnamed variable $1 to the log comment. It is checked
    # for a match as: m/$regex/s
    log_regex => 'bug.*?:\s*(.*)'
    },
	    

bug 441:Improved the documentation of policy log_template by adding
an example log message.
	    

# Minimum number of characters log message.
minimum_log_message_size => {
    enabled => 1,
    size => 50
	    },
	    

# Format of label names (tag or branch names) defined as
# regular expressions.
label_name => {
    enabled => 1,
    names => [
	      # Convention for official releases.
	      # For example:
	      # SCMBUG_RELEASE_0-2-7
	      '^.+?_RELEASE_[0-9]+-[0-9]+-[0-9]+$',

	      # Convention for development builds.
	      # For example:
	      # SCMBUG_BUILD_28_added_a_policies_mechanism
	      '^.+?_BUILD_[0-9]+_.+$',

	      # Convention for branches.
	      # For example:
	      # b_experimenting_with_policies_on_glue_side
	      '^b_.+$',

	      # Convention for private developer tags. Uses
	      # the developer's initials (either 2 or 3).
	      # For example:
	      # p_kpm_prior_to_bug353_stabilization_fixes
	      '^p_[a-zA-Z][a-zA-Z]?[a-zA-Z]_.+$'
	      ]
	  }
	    

#
# Presence of bug ids. There are 3 options:
#
# - 'required'. A bug id must be specified during each
#   activity. Activities without a bug id will not be permitted.
#
# - 'optional'. If a bug id is supplied, the activity will be
#   integrated. If not the activity will be permitted to go
#   through in the SCM system, but without bug-tracking
#   integration.
#
# - 'none'. Never integrate activities regardless. This is
#   different than flagging the glue inactive. The remaining
#   policies are still enforced were applicable.
#   (e.g. policy minimum_log_message_size).
#
# This policy is ALWAYS enabled
presence_of_bug_ids =>  {
    value => 'required'
    },
	    

# The SCM user issuing an activity must be the user to which
# the bug is assigned
valid_bug_owner => {
    enabled => 1,
}
	    

# The bug against which an activity is issued must be in an
# open state
open_bug_state => {
    enabled => 1
    },
	    

# Send an email after a successful activity (both committing
# and labeling).
mail_on_success => {
    enabled => 1,
    # Sending email when a tag is moved or deleted in CVS can
    # be annoying, since multiple emails are sent per
    # directory(but not when a tag is added). mail_on_label
    # can disable that behavior.
    mail_on_label => 1,
    values => {
	To => 'replace_with_commit_mailing_list_email@exampledomain.com',
	# Must be a valid email address
	From => 'Scmbug <replace_with_mailing_list_owner_email@exampledomain.com>',
	# Defaults to localhost if left empty
	Smtp => 'replace_with_mail_server.domain.com'
    },
    # List of users that can be notified regardless.
    mail_scm_user => 1,
    mail_bug_owner => 1,
    mail_bug_reporter => 1,
    mail_bug_monitors => 1,
    # When labeling, the product owners can also be notified.
    mail_product_owners => 1
}
	      

4.3. Integration Of SCM Log Messages

When a software change occurs in the SCM system, a log message may be used to describe the change. Using an activity_commit integration request, this log message is inserted in the bug-tracking system against the specified bug id. The log message is complemented by the list of files affected by the changeset, as shown in Figure 4-18

Added a glossary, and a document conventions section, just
like the Bugzilla Guide uses. Began linking names of systems/tools to
the glossary, and using a url to their webpage there. This will
unclutter the pdf version of the document from url links inlined with
content.




Affected files:
---------------
1.7 --> 1.8 system/doc/manual/about.sgml
1.7 --> 1.8 system/doc/manual/bugtracking-backends.sgml
NONE --> 1.1 system/doc/manual/conventions.sgml
NONE --> 1.1 system/doc/manual/glossary.sgml
1.12 --> 1.13 system/doc/manual/manual.sgml.in
1.8 --> 1.9 system/doc/manual/scm-frontends.sgml
1.9 --> 1.10 system/doc/manual/tools.sgml
	

4.4. Integration Of SCM Labeling Operations

When a tag or branch operation is issued in the SCM system, a name is used to describe this software labeling operation. Using an activity_tag integration request, this label is inserted in the list of possible versions of the product in the bug-tracking system.

5.1. CVS

CVS is the Concurrent Versions System, the dominant open-source network-transparent version control system.

Scmbug supports verification checks, integration of log messages with the bug-tracking system, and integration of labeling operations for CVS. Various deficiencies of CVS introduce complications in integration. It is recommended that users of CVS upgrade to Subversion.

CVS does not require users to enter a log comment when directories are added in a repository. Scmbug does not overcome this limitation, even though it is possible to do so.

Another limitation of CVS is that it does not provide an integration hook on 'cvs admin -o'.

The verification hook of CVS 1.11.x does not provide the list of files that will be modified. As a result, the Valid product name policy cannot be set to auto for CVS 1.11.x. This policy will be implemented in the future for CVS 1.12.x and, if possible, for CVSNT.

A major drawback of CVS is it's lack of atomic transactions. As a side-effect, when the same log message is used to commit files in two separate directories, two integration actions occur using the same log message. Duplicate log messages are then entered in the bug-tracking system. An example of this can be observed in bug 353, in comments 2 and 3 . It is possible to introduce logic in the Scmbug daemon that can solve this problem.

A common limitation of other systems integrating CVS with bug-tracking resulted from the inadequate mechanism CVS 1.11.x uses to provide the list of affected files in a commit trigger. For each file, the old version, new version, and the filename, all separated by commas, can be passed as command-line arguments to an integration trigger script. When the filenames, or the directory in which the files reside, contain either commas or whitespaces, a processing script using a single regular expression to parse these arguments will get confused. Some systems addressed this by requiring source modifications to the CVS binary, and distributed patches for it. Scmbug addresses this issue by employing a stateful parser. Using this parser, the probability of files and directories with whitespaces or commas contained in their names to confuse the integration glue is marginal. For example, the filename shown in Figure 5-1 is accepted.

a file with spaces,NONEs, commas, digits,1.1,2.numbers close to dots.1.2,NONe.txt
      

Scmbug has been verified to work against the following releases of CVS:

• 1.11.21

• 1.12.13

• CVSNT 2.5.03 Build 2260

5.2. Subversion

Subversion is a compelling replacement for CVS.

Scmbug supports verification checks, integration of log messages with the bug-tracking system, and integration of labeling operations for Subversion.

Subversion is not yet capable of using a predefined log template when the user's editor is opened to enter a log comment. As a result, the log template expected by Scmbug must be entered by the user.

Scmbug has been verified to work against the following releases of Subversion:

• 1.0.6

• 1.1.3

• 1.2.3

• 1.3.0

5.3. Other SCM Systems

Additional SCM frontends can be supported by Scmbug. Developers and system integrators of the following SCM systems are strongly encouraged to contribute an SCM integration frontend:

• Aegis

• Arch

• Bazaar-NG

• Bitkeeper

• Clearcase

• GIT

• Katie

• Mercurial

• Monotone

• OpenCM

• Perforce

Developing a frontend requires:

• Committing to support this frontend in future releases of Scmbug.

• Creating a new frontend module named src/lib/product/Glue/FrontendName.pm.in. The CVS frontend src/lib/product/Glue/CVS.pm.in serves as a good example.

• Updating src/lib/product/Glue/Glue.pm.in:check_configuration accordingly.

• Updating the configuration management files configure.in and Makefile.in to autogenerate, and autocleanup the new frontend.

• Updating the install-tools rule of Makefile.in to install the new frontend from source.

• Creating a new directory named src/glue/templates/frontendname that includes template hook/trigger scripts. The CVS trigger scripts in src/glue/templates/cvs serve as a good example.

• Updating the Glue Installer src/scripts/install_glue.pl.in and its manpage doc/manpages/install_glue.sgml.1.in to support the new frontend.

• Updating the VDD Generator src/scripts/vdd_generator.pl.in and its manpage doc/manpages/vdd_generator.sgml.1.in to support the new frontend.

• Updating the documentation in doc/manual/content to reflect support for the new frontend.

6.1. Bugzilla

Bugzilla is an enterprise-class piece of software that tracks millions of bugs and issues for hundreds of organizations around the world.

Bugzilla does not provide a public interface for SCM integration. Nevertheless, the Scmbug daemon attempts to reuse functionality already available in the Perl-based Bugzilla libraries. As a result, the source code used to host a Bugzilla instance must be locally accessible by the daemon. The installation_directory variable is used to define the location of the Bugzilla source installation as shown in Figure 6-1.

# Used for Bugzilla and RequestTracker.
#
# Path to the directory of the bugtracker sources providing an
# API that the daemon can use
installation_directory => '/usr/share/bugzilla/lib'
	    

Additionally, the installed_locally variable is used to flag whether Bugzilla is installed locally on the same machine the daemon is running as shown in Figure 6-2. This is required to flush Bugzilla's version cache when SCM tags are added or deleted, and immediately reflect tag manipulation to Bugzilla's user interface.

# Used only for Bugzilla.
#
# Flags whether the live bugtracker instance is installed
# locally on the same machine the daemon is running
installed_locally => 1,
	    

For example, it is possible to install Bugzilla in machine A, and install a duplicate Bugzilla source in machine B where Scmbug is installed. In this scenario installation_directory would be set to Bugzilla's source code path on machine B, but the variable installed_locally would be set to 0.

The Bugzilla developers are planning to provide a formal SCM integration interface in future releases.

As of version 2.22.0, Bugzilla does not yet support a mapping of the SCM username to a Bugzilla username. An SCM to bug-tracking username mapping is accomodated by the integration daemon using the userlist variable, as described in Section 4.2.8.

Bugzilla currently lacks a per-bug comment id. This makes it very difficult to accurately report the comment ids in a VDD for Bugzilla. Currently, the VDD comment ids are prefixed with the string "inaccurate_".

Scmbug has been verified to work against the following releases of Bugzilla:

• 2.14.2

• 2.16.5

• 2.18rc2

• 2.19.2

• 2.20.0

• 2.22.0

6.2. Mantis

Mantis is a web based PHP/MySQL-based bugtracking system.

Mantis does not provide a public interface for SCM integration. However, the Scmbug daemon includes a native Perl-based bug-tracking backend for integration with Mantis. Configuration of the variables installation_directory(Figure 6-1) and installed_locally(Figure 6-2) is not required.

Mantis supports installation with multiple database backends. The daemon configuration variable database_vendor defines the selected database backend, as shown in Figure 6-3.

# Valid values are the ones accepted by the Perl DBI.
#
# For Bugzilla, this value is ignored
#
# For Mantis, *some* valid values (there are others) are:
# - 'mysql'
# - 'Pg'
database_vendor => 'mysql',
	   

The Mantis developers are planning to provide a formal SCM integration interface in future releases.

As of version 0.19.0, Mantis does not yet support a mapping of the SCM username to a Mantis username. An SCM to bug-tracking username mapping is accomodated by the integration daemon using the userlist variable, as described in Section 4.2.8.

Scmbug has been verified to work against the following releases of Mantis:

• 0.19.0

• 1.0.0rc3

6.3. Request Tracker

Request Tracker is a web based request tracking system written in object-oriented Perl.

Request Tracker provides a public interface for SCM integration. The Scmbug daemon reuses functionality already available in the Perl-based Request Tracker libraries. As a result, the library code used to host a Request Tracker instance must be locally accessible by the daemon. The installation_directory variable is used to define the location of the Request Tracker installation as shown in Figure 6-4.

# Used for Bugzilla and RequestTracker.
#
# Path to the directory of the bugtracker sources providing an
# API that the daemon can use
installation_directory => '/usr/share/request-tracker3.4/lib'
	    

This backend integration with Request Tracker assumes the product names in the glue.conf match the queue names set in the Request Tracker.

The activity_tag integration action is not yet supported.

As of version 3.4.5, Request Tracker does not yet support a mapping of the SCM username to a Request Tracker username. An SCM to bug-tracking username mapping is accomodated by the integration daemon using the userlist variable, as described in Section 4.2.8.

Scmbug has been verified to work against the following releases of Request Tracker:

• 3.4.5

6.4. Other Bug-tracking Systems

Additional bug-tracking backends can be supported by Scmbug. Developers and system integrators of the following bug-tracking systems are strongly encouraged to contribute a bug-tracking integration backend:

• AntHill

• Bosco

• debbugs

• Double Choco Latte

• Eventum

• GForge

• GNATS

• Helis

• ITracker

• phpBugTracker

• Roundup

• Scarab

• Trac

• TUTOS

• Workbench

Developing a backend requires:

• Committing to support this backend in future releases of Scmbug.

• Creating a new backend module named src/lib/product/Daemon/BackendName.pm.in. The Bugzilla backend src/lib/product/Daemon/Bugzilla.pm.in serves as a good example.

• Updating src/lib/product/Daemon/Daemon.pm.in:read_configuration accordingly.

• Updating the configuration management files configure.in and Makefile.in to autogenerate, and autocleanup the new backend.

• Updating the install-server rule of Makefile.in to install the new backend from source.

• Updating the documentation in doc/manual/content to reflect support for the new backend.

7.1. Glue Installer

The command scmbug_install_glue is used to install the integration glue in an SCM repository. Existing hooks used in the SCM system are not overwritten.

The --binary-paths configuration option should be set to a list of paths that include all binaries needed by the integration tools and the SCM system. This includes the tools diff, xsltproc, docbook2pdf, docbook2html and the SCM system's binaries. The --bug configuration option should be set to the id of a bug in the bug-tracker against which the integration glue installation will be documented.

An example installing the glue in a Subversion repository under UNIX is shown in Figure 7-1.

$ scmbug_install_glue --scm=Subversion --product=TestProduct \
  --repository=/tmp/testrepository --bug=770 --binary-paths=/bin,/usr/bin \
  --daemon=127.0.0.1
 This is the installation script of the Scmbug glue.
 The glue will be installed in repository: /tmp/testrepository.
 This is a repository for the Subversion SCM tool.
 The product name in the bug tracking system is TestProduct.
 The integration glue will be committed against bug 770.
 The IP address of the Scmbug integration daemon to contact is 127.0.0.1.
 The binary paths used are: /bin,/usr/bin
 -------------
 Press Enter to continue or Ctrl-C to cancel

Glue processing has been prepared in /tmp/Scmbug.30670
Installing part1
Check everything there before I commit or hit Ctrl-C to exit

Glue processing has been prepared in /tmp/Scmbug.30670
Installing part2
Check everything there before I commit or hit Ctrl-C to exit
        

Under Windows, the paths supplied to the installer should have directories separated with a forward (/) slash. Figure 7-2 shows an example running the installer under Windows. Figure 7-2. Glue Installation in a CVSNT repository under Windows. $C:\Program Files\Scmbug\bin>scmbug_install_glue.pl --scm=CVS --product=sdvel \ --repository=c:/cvsroot --bug=22 --daemon=192.168.136.140 \ --binary-paths="C:/Program Files/CVSNT"

---

7.1.1. CVS

Integration glue can be installed in both local and remote CVS repositories.

After installation, the file <CVS_REPOSITORY_PATH>/CVSROOT/etc/scmbug/glue.conf holds the configuration of the glue.

CVSNT uses the two variables Name and Root when configuring a repository, instead of only the CVSROOT variable. When hooks execute, CVSNT sets CVSROOT to be equal to Name. By default, CVSNT sets Name omitting the drive letter. The hooks will not execute if Name is not set to the full path of the repository since $CVSROOT will be referring to a path that does not exist. An example invalid Name/Root configuration is shown in Figure 7-3. An example valid Name/Root configuration is shown in Figure 7-4. Figure 7-3. Example invalid Name/Root for CVSNT. Name: /Projects Root: C:/cvsrepos/Projects Figure 7-4. Example valid Name/Root for CVSNT. Name: C:/cvsrepos/Projects Root: C:/cvsrepos/Projects Setting Name to be equal to Root produces the warning shown in Figure 7-5. The compatibility problems seem to refer to some clients simply not parsing a CVSROOT with a drive letter in it. If your development environment includes UNIX clients, and problems do occur, one alternative is to let Name lack a drive letter and manually edit the hook files to include the full repository path. Figure 7-5. CVSNT warning when Name is set to Root. Using drive letters in repository names can create compatibility problems with Unix clients and is not recommended. Are you sure you want to continue ?

label_directories => [
		      'tags',
		      'branches'
		      ]
	

7.2. Version Description Document Generator

Since SCM changes are integrated with bug-tracking, it is possible to produce a list of changes that occured for a particular version of a software at a level that's higher than source changes.

ChangeLog information derived strictly from the SCM system, such as a report produced using the cvs2cl tool for CVS or using 'svn log' in Subversion, is overly detailed. It describes software changesets at a lower level, which interests mostly developers. It is of little value to a user simply interested in a summary of added features. Moreover, when multiple changesets are committed in response to a defect, such a document becomes lengthy. It takes considerable time to follow the history of changes and decipher if, or how, a defect was corrected.

Instead, a VDD reports at a higher level a summary of the features/defects worked on and why, using information recorded in the bug-tracking system. It provides additional useful information such as resolution status, bug owner, severity, and priority. It also reports what changes occured at a lower level in the SCM system per bug, effectively superseding ChangeLog documents produced strictly from the SCM system. Without integration of SCM with bug-tracking, this level of detail in a release document would not be possible.

Given two SCM label names (tag or branch names), this tool queries the SCM system for the dates the labels were applied. It then queries the bug-tracking system to produce a report of the bugs worked between that date range. A VDD can additionally reflect decisions of the development team which are not documented in the SCM logs, such as choosing to not add a feature, resolving it as WONTFIX. It may also display bugs that were added in the period between releases but not worked yet, alerting users of newly discovered defects.

A VDD can be generated using the command scmbug_vdd_generator. An example producing this document is shown in Figure 7-7.

$ scmbug_vdd_generator --scm=Subversion --product=TestProduct \
  --repository=/tmp/testrepository --from=SCMBUG_RELEASE_0-8-1 \
  --to=SCMBUG_RELEASE_0-8-2
        

The output of this tool is a collection of files. An XML file is produced that contains the result of the VDD query. This file is also transformed using XSLT into a Docbook 4.2 SGML file. Finally, this SGML file is processed using Docbook tools to produce PDF and HTML output.

8.1. Availability

Scmbug is available for UNIX and Windows systems. It is expected to work with Perl version 5.6.1 or later and has been confirmed to work with Perl version 5.8.4. Dependencies on additional programs are described in Section 8.2.

The project's webpage contains the most up to date information on the project, including the latest release and manual. A users mailing list is available for subscription, or simply for sending email. The project's bug-tracking system contains the latest TODO list. Source code access to developers is available using anonymous CVS as shown in Figure 8-1 or through ViewCVS.

bash$  cvs -d:pserver:anonymous@cvs.mkgnu.net:/projects/scmbug/cvsroot login
Password:
bash$  cvs -d:pserver:anonymous@cvs.mkgnu.net:/projects/scmbug/cvsroot co .
          

8.2. Installation

8.2.1. System

Under UNIX, Scmbug is available in the form of Debian and RPM packages. The provided packages are:

• scmbug-common: common libraries.

• scmbug-doc: documentation.

• scmbug-tools: tools that can install the integration glue in an SCM repository and enhance the experience of integrating SCM with bug-tracking.

• scmbug-server: the integration daemon.

Under Windows, the entire Scmbug system is available in the form of a single .zip file. It must be manually installed in C:/Program Files/Scmbug. It requires ActiveState ActivePerl installed in C:/Perl/bin/perl, and a temporary directory called C:/Temp.

Source code distributions are also available. Figure 8-2 shows how the system can be configured and installed from source. It is possible to choose a different destination of the libraries and binaries of Scmbug both in UNIX and Windows systems at configuration time. If you are configuring from source code, running './configure --help' can provide more information.

Figure 8-2. Installation of the system from source.

	bash$ ./configure
	bash$ make
	bash$ su
	bash# make install-common
	bash# make install-doc
	bash# make install-tools
	bash# make install-server
        

Installing all these packages will NOT automatically integrate an SCM repository with a bug-tracking system. It will only install the basic software needed to do so. A user must configure the Integration Daemon and start it as shown in Figure 8-3. Then, a user must run the Glue Installer to install the Scmbug integration in an SCM repository. Figure 8-3. Integration daemon start. Starting the Integration Daemon in UNIX systems: bash# /etc/init.d/scmbug-server start Starting the Integration Daemon in Windows systems: C:\> cd C:/Program Files/Scmbug/etc/init.d C:/Program Files/Scmbug/etc/init.d> scmbug-server.bat

When specifying paths in Windows, either in the glue installer, the glue configuration file, or the integration daemon, paths should have directories separated with a forward (/) slash.

There are various dependencies on the packages provided. Both dependencies on other packages, and on Perl modules. If they are ignored, the Integration Daemon and the Integration Tools will detect the missing dependency and refuse to execute.

bash$ su
bash# perl -MCPAN -e "install Mail::Sendmail"
bash# perl -MCPAN -e "install XML::Simple"
                

C:\> ppm
PPM - Programmer's Package Manager version 3.1.
Copyright (c) 2001 ActiveState Corp. All Rights Reserved.
ActiveState is a devision of Sophos.

Entering interactive shell. Using Term::ReadLine::Stub as readline library.

Type 'help' to get started.
ppm> install Mail-Sendmail
ppm> install XML-Simple
                

bash$ su
bash# perl -MCPAN -e "install DBI"
        

C:\> ppm
PPM - Programmer's Package Manager version 3.1.
Copyright (c) 2001 ActiveState Corp. All Rights Reserved.
ActiveState is a devision of Sophos.

Entering interactive shell. Using Term::ReadLine::Stub as readline library.

Type 'help' to get started.
ppm> install DBI
                

	bash$ su
	bash# perl -MCPAN -e "install DBD::mysql"
        

C:\> ppm
PPM - Programmer's Package Manager version 3.1.
Copyright (c) 2001 ActiveState Corp. All Rights Reserved.
ActiveState is a devision of Sophos.

Entering interactive shell. Using Term::ReadLine::Stub as readline library.

Type 'help' to get started.
ppm> install DBD-mysql
                

8.3. Upgrading

Upgrading to newer versions of Scmbug is possible. It first requires understanding the issues involved in running non-matching versions of the Glue and Daemon.

---

8.3.1. Issues

The communication protocol between the Glue and the Daemon is upgraded and is backwards-incompatible when the minor version number of Scmbug increases. For example, SCMBUG_RELEASE_0-1-x and SCMBUG_RELEASE_0-2-x are not compatible, but SCMBUG_RELEASE_0-2-1 and SCMBUG_RELEASE_0-2-8 are.

During SCM events activity, if the Glue detects an incompatible version of the Daemon, it will refuse to continue.

Running incompatible versions of the Glue and Daemon can result in developers being locked out of an SCM repository. For example, when using CVS it could result in the integration failing to commit any changes, leading into a dead-end. This would prohibit disabling the Glue in its entirety, and require manually editing the repository locally using RCS commands. Certainly, an SCM repository can always be brought back to a working state by a competent administrator.

Since version SCMBUG_RELEASE_0-3-3, the Glue Installer is able to safely upgrade the integration to newer versions. It first completely disables all SCM hooks installed by Scmbug, upgrades the Glue code, and then enables the hooks. During the last step, the Daemon does not need to be contacted, since the hooks are not yet active.

If you understand the implementation internals of Scmbug you will be able to determine whether a new feature is implemented in the Glue or the Daemon, and upgrade only the Glue or only the Daemon. One example where you might not want to upgrade both the Glue and Daemon is if you have a lot of SCM repositories and you need a new feature that has been implemented only on the Daemon. Upgrading only the daemon is a lot easier than first upgrading all repositories. Another example would be upgrading only the Glue of a single SCM repository if you need a new Scmbug feature only in that repository.

If in doubt, upgrade everything.