3.3.1. Bugzilla Email Gateway

SCM systems can integrate their actions with Bugzilla using the Bugzilla email gateway. Hook scripts installed in an SCM system can email the results of the system's actions to an email account configured to parse the email and process it accordingly. An example of such a configuration is available from Steve McIntyre's web page.

This approach is not synchronous. For example, if a user accidentally commits against the wrong bug number, or a bug against which he is not the owner, the SCM system will proceed with the commit action regardless, without giving the user the option to correct his actions. Additionally, if the email gateway is not active, the developer will not be immediately aware that integration failed.

3.3.2. CVSZilla

Tony Garnock-Jones' CVSZilla integrates SCM events produced by CVS with Bugzilla. It also extends CVS to give rudimentary support to "change-sets", or "transactions".

CVSZilla does not support integration of events produced by any SCM system in a generic way. It modifies the Bugzilla schema and does not work with future versions of Bugzilla. Finally, it assumes that the TCP port used by MySQL is accessible from the machine hosting the CVS repository.

The last assumption does not always hold true, especially when a bug-tracking system is used to track development of mobile developers (laptop users), needing the flexibility to work both locally and remotely, on multiple projects, across different organizational units. Experience has shown that this is a common scenario in organizations with limited hardware, software, or labor resources, such as an academic environment.

For example, imagine integrating CVS actions from a repository hosted on a personal laptop with a Bugzilla instance that needs to be publicly accessible from the Internet. This same bug-tracking system is used for collaboration with other mobile developers of a different organization on a joint project hosted on a third machine. Integration over the public Internet is not possible without opening the MySQL database port Bugzilla uses. Opening this port is unnecessarily insecure, exposing access to other applications hosted on the same database system. The Scmbug daemon exposes the minimum required integration interface between an SCM system and a bug-tracking system.

3.3.3. Other Integration Systems

Commercial products concentrate only on integrating a particular SCM system with a particular bug-tracking system, in a proprietary way. They do not attempt to define a public SCM to bug-tracking integration interface, and solve the integration problem once and for all.

Scmbug is an effort for defining an SCM to bug-tracking integration interface and mechanism that will permit integration of any SCM system with any bug-tracking system.

4.4.1. Enabled Integration

SCM events will be integrated with bug-tracking only if the integration glue is enabled. This can be controlled in the glue configuration file using the enabled variable, as shown in Figure 4-3.

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

4.4.2. Supported SCM version

SCM tools may work considerably different between separate versions. For example, CVS changed during the 1.12.x series the format of command-line arguments supplied to integration hooks. Appropriate support is needed to handle their idiosynchracies. The SCM tool's version is detected at runtime, and interaction with the tool is handled accordingly.

One of the problems with some SCM systems is that they may unset the PATH variable (e.g. Subversion in 1.2.x). The list of paths to the tool's binaries must be supplied in the glue configuration file using the binary_paths variable, as shown in Figure 4-4. It is verified at runtime that each binary needed by an SCM tool is present in only one path from the list supplied, to avoid accidentally invoking the wrong version of the tool due to an incomplete installation of the SCM tool.

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

4.4.3. Use Of A Log Message Template

The log message supplied to the SCM system when committing a software change is verified to match a log template expected by Scmbug. Two regular expressions describe how the bug id and log comment will be identified. These are defined as part of the log_template policy variable as shown in Figure 4-5, through the variables log_bugid_regex and log_body_regex.

A way to split a list of multiple bug ids into separate ids is also described with a regular expression through the variable log_bugid_split_regex. This is needed in order to permit special characters to preceed a bug number. For example, instead of separating bug ids using a whitespace or comma, one may want to also prefix a bug id with a '#'. Bug-trackers may then autolinkify in their comments a bug id that is prefixed by a '#' (e.g. Bugzilla). An example log message accepted by these expressions is shown in Figure 4-6.

log_template =>  {
    # The log_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
    log_bugid_regex => 'bug\s*([\d|\s|,|#]*?):',
    # The log_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/
    log_bugid_split_regex => ',\s?#|\s?#|,|\s+',
    # The log_body_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_body_regex => 'bug.*?:\s*(.*)'
    },
	    

This template can be customized when the Scmbug codebase is configured, prior to installation. The arguments --with-log-template-bugid-regex=<regular_expression>, --with-log-template-bugid-split-regex=<regular_expression>, and --with-log-template-body-regex=<regular_expression> can be passed to configure, shown in Figure 8-4.

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

4.4.4. Presence Of Distinct Bug Ids

The log message supplied to the SCM system when committing a software change is verified to include only distinct bug ids.

4.4.5. Valid Log Message Size

It is verified that the log message supplied to the SCM system system meets a configurable minimum log message size limit. This behavior is defined in the glue configuration file using the minimum_log_message_size policy variable, as shown in Figure 4-7.

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

4.4.6. Convention-based Labeling

It is verified that the names used in labeling operations, such as creation of tags or branches, match a configurable label naming convention. This behavior is defined in the glue configuration file using the label_name policy variable, as shown in Figure 4-8.

# 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]_.+$'
	      ]
	  }
	    

Labels for official releases can correspond to versions of the software that will be made public to users, and are applied by release managers.

Developments builds can be helpful in development environments that produce weekly builds, as a checkpoint of a stable codebase. They are applied by release managers. They can also correspond to development milestones that will incorporate specific features, even though the codebase is not ready for an official release.

Branches can be created when maintaining a previous, already released, version of a software. For example, to correct critical bugs or apply security fixes. They are applied by release managers. They can also be created when a feature may require a considerable amount of time to implement while disrupting the main codebase drastically (e.g. a core API change). A branch is created, the feature is implemented, and when it is deemed stable it is merged in the main codebase.

Private developer tags are very similar to development builds. They can be applied directly by developers, instead of strictly release managers, and should be thought of as personal, developer milestones applied at stable points. The developers may be working on features of increased complexity, or features that will require a significant amount of time to complete. Incrementally applying private developer tags that match distinct progress steps can help a developer debug a regression in his implementation. As another example, assume a developer implements a feature using a specific algorithm. Later, software requirements change, and the developer is tasked to reimplement this feature using a different algorithm. The developer can first apply a private tag, and then reimplement the feature using the new algorithm. If it is later determined that the feature should revert back to using the original algorithm, the developer can retrieve the original implementation using the private developer tag he had applied. In a sense, private developer tags can be applied at a finer granularity than group development builds.

4.4.7. Presence Of Bug Ids

The log message supplied to the SCM system when committing a software change may be required to include at least one bug id. This is determined using the presence_of_bug_ids policy variable, as shown in Figure 4-9.

#
# 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'
    },
	    

4.4.8. Valid SCM To Bug-tracking Username Mapping

All integration requests must include the SCM username of the user issuing an integration request. This username must be mapped to the username of the user in the bug-tracking system. Bug-tracking systems that do not support SCM usernames are accomodated through a username mapping list defined in the daemon configuration file using the userlist variable. Three mapping mechanisms are available:

• LDAP. An LDAP directory is accessed to map the SCM username, as one LDAP attribute, into the bug-tracking username defined by another LDAP attribute. This can be configured in the daemon configuration file using the mapping_ldap variable, as shown in Figure 4-10.

  Figure 4-10. SCM to bug-tracking username mapping based on mapping_ldap.

  # This is a mapping based on LDAP. ldap_scm_username_attribute
  # defines the LDAP attribute that will be used to match the
  # SCM username. The SCM username will be mapped into the
  # bug-tracking username defined by
  # ldap_bugtracking_username_attribute.
  mapping_ldap => {
      enabled => 0,
      ldap_server => '127.0.0.1',
      ldap_port => '389',
      # A binddn (e.g. cn=default) that has access to read all
      # attributes
      ldap_binddn => 'replace_with_binddn',
      # The password of the binddn that has access to read all
      # attributes
      ldap_binddn_password => 'replace_with_binddn_password',
      # The BaseDN in which to search for the
      # ldap_scm_username_attribute (e.g. "ou=People,o=Company")
      ldap_basedn => 'replace_with_basedn',
      # The name of the attribute containing the user's SCM
      # username
      ldap_scm_username_attribute => 'uid',
      # The name of the attribute containing the user's
      # bug-tracking username
      ldap_bugtracking_username_attribute => 'mail',
      # LDAP filter to AND with the ldap_scm_username_attribute
      # for filtering the list of valid SCM users.
      ldap_filter => ''
  },
  	        

• List of regular expressions. A list of regular expressions describe how the SCM username will be matched and how it will be transformed into a bug-tracking username using the mapping_regexes variable. This can be configured in the daemon configuration file as shown in Figure 4-11.

  Figure 4-11. SCM to bug-tracking username mapping based on mapping_regexes.

  # This is a mapping based on regular expressions. The first
  # expression defines how the SCM username will be matched. The
  # second defines how it will be transformed, and uses the
  # unnamed variable $1 that was described by the first
  # expression. The mapping is checked for a match as:
  # m/$first_regex/
  # and is applied as: s/$first_regex/$second_regex/
  mapping_regexes => {
      enabled => 0,
      values => {
      # This is an example of mapping a Windows Domain user
      # from 'DOMAIN\user' to 'user@EMAIL_DOMAIN.com'
      '^DOMAIN\\\\(\w+)$' => '$1\@EMAIL_DOMAIN.com',
      # This is an example of mapping a UNIX user from
      # 'example_user' to 'example_user@exampledomain.com'
      '^(\w+)$' => '$1\@exampledomain.com'
      }
  },
  	        

• Direct. A direct one-to-one mapping of an SCM username to a bug-tracking username using the mapping_values variable. This can be configured in the daemon configuration file as shown in Figure 4-12.

  Figure 4-12. SCM to bug-tracking username mapping based on mapping_values.

  # This is a one-to-one mapping of SCM usernames to bugtracking
  # usernames. Mappings in this list override mappings from
  # mapping_regexes.
  mapping_values => {
      enabled => 0,
      values => {
      'DOMAIN\\example_user' => 'example_user@DOMAIN.com',
      'example_user2' => 'example_user2@exampledomain.com'
      }
  },
  	        

If the SCM username already matches the bug-tracking username, these mappings can be disabled in the daemon configuration file as shown in Figure 4-13. If any of these mappings are enabled, they are executed in the order presented here. Mappings based on mapping_ldap are appiled first. Mappings based on mapping_regexes are applied second and can override a mapping based on mapping_ldap. Mappings based on mapping_values are applied last and can override all other mappings.

mappings => {
    # Enable SCM username translation. This flag must be
    # turned on for any of the mappings that follow to apply.
    enabled => 0,
	        

The username verification is applied case sensitive. This can be configured in the daemon configuration file as shown in Figure 4-14. For example, Microsoft Active Directory tends to capitalize the first letter of each word in the email address. The email address returned does not match the email address reported by the bug-tracker in lowercase, and needs case_sensitive_username_verification to be disabled.

# Apply a case sensitive username verification.
case_sensitive_username_verification => 0,
	        

4.4.9. Valid Product Name

An activity_verify integration request must refer to bug ids filed against the SCM system's associated product name in the bug-tracking system. This behavior is optional and can be configured in the glue configuration file using the valid_product_name policy variable, as shown in Figure 4-15.

# The bug against which an activity is issued must be filed
# against a valid product name.
valid_product_name => {
    enabled => 1
    },
	      

Regardless of the configuration of the valid_product_name policy, the product name is required by other parts of the integration. For example, it is needed to detect labeling operations in Subversion, as shown in Figure 7-7, for Mail notification and for Autolinkification. It can be specified in the glue configuration file using the product_name_definition policy variable in two ways:

• Manually defined. All SCM activity in the repository will be integrated against a single product name in the bug-tracker. This requires setting the product_name_definition policy's type to manual and providing a product name in value, as shown in Figure 4-16.

  Figure 4-16. Manually defined product name.

  # Product name definition. There are 2 options:
  #
  # - type is 'manual'. Each bug id supplied during commit
  #   messages must be filed against the product name
  #   specified in value.
  #
  # This policy is ALWAYS enabled
  product_name_definition => {
      type => 'manual',
      value => 'TestProduct'
      },
  	      

• Automatically detected. Some organizations may follow a development model that permits multiple products to be hosted under the same SCM repository. For example, multiple product names in the bug-tracking system may correspond to multiple branches in the SCM system. Scmbug can autodetect the appropriate product name by consulting a list of regular expressions that describe how to match the product name in a path in a repository.

  Figure 4-17 shows a configuration example that can autodetect from the repository structure of Figure 4-18 the list of product names in Figure 4-19. When a file from one of the directories shown in Figure 4-18 is commited, the appropriate product name shown in Figure 4-19 will be autodetected.

  Figure 4-17. Automatically detected product name.

  # Product name definition. There are 2 options:
  #
  # - type is 'auto'. The product name will be
  #   autodetected. Value must be a comma(,)-separated list of
  #   regular expressions. Each regular expression must set the
  #   unnamed variable $1 to the product name.
  #
  # This policy is ALWAYS enabled
  product_name_definition => {
      type => 'auto',
      value => 'dir/prefix1/productMain_(.+?)/,dir2/(.+?)/,dir3/(?:trunk|tags|branches)/(.+?)/'
      },
  	      

  Figure 4-18. Repository structure with product names that can be automatically detected.

  dir/prefix1/productMain_subproductA/trunk
  dir/prefix1/productMain_subproductA/tags
  dir/prefix1/productMain_subproductA/branches
  dir/prefix1/productMain_subproductB/trunk
  dir/prefix1/productMain_subproductB/tags
  dir/prefix1/productMain_subproductB/branches
  dir2/productA_3-1/trunk
  dir2/productA_3-1/tags
  dir2/productA_3-1/branches
  dir2/productB
  dir2/productB_multiuser
  dir3/trunk/productC
  dir3/tags/productC
  dir3/branches/productC
  	      

  Figure 4-19. Automatically detected product names from Figure 4-18.

  subproductA
  subproductB
  productA_3-1
  productB
  productB_multiuser
  productC
  	      

  Another example where multiple products may be required would be a contracting company maintaining all their contracts in the same SCM repository but using separate product names in the bug-tracking tool.

  We must note that, from an SCM perspective, hosting multiple products that share a common codebase in the same SCM system may not be the ideal way to go. Organizations that follow this development model may want to consider developing their common codebase in it's own SCM repository, as a separate product. They can then import the common code as a vendor branch in multiple SCM repositories, each corresponding to a single product name they wish to publicly release. More information on vendor branches can be found in the CVS and Subversion manuals.

  Automatically detected product names are not supported for CVS or for Git.

4.4.10. Valid Bug Owner

It is verified that the SCM user issuing an activity_verify integration request is the owner or one of the owners of the bug against which subsequent integration requests will be issued. This behavior is optional and can be configured in the glue configuration file using the valid_bug_owner policy variable, as shown in Figure 4-20.

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

4.4.11. Anonymous SCM Username

It is always verified that the SCM system supplied a username when generating activity. However, some SCM systems may not always supply an SCM username. One example is Subversion running an svnserve daemon granting anonymous access. The username of the SCM user under which activity should be generated can be optionally configured in the glue configuration file using the anonymous_scm_username policy variable, as shown in Figure 4-21.

# All integration activity must originate from a specific SCM
# user. If the SCM system does not provide the SCM user
# information (e.g Subversion running an svnserve daemon with
# anonymous access), assume the activity originated from a
# specific SCM user
anonymous_scm_username => {
    enabled => 0,
    value => 'anonymous_scm_user'
    },
	    

4.4.12. Open Bug State

It is verified that the bug against which an activity_verify integration request is issued must is in an open, active state in the bug-tracking system. This behavior is optional and can be configured in the glue configuration file using the open_bug_state policy variable, as shown in Figure 4-22.

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

4.5.1. Mail Notification

An email can be sent when an integration activity, either commiting or labeling, is accepted. This is defined in the glue configuration file using the mail_on_success policy variable, as shown in Figure 4-23. Emails can also be sent after a failed commit activity if the SCM system overshadows and does not report the error message using the mail_on_failure policy variable.

For example, Subversion does not report error messages of its post-commit hook.

#
# Send email notifications after integration activity
#
mail_notification => {
	# Send an email after a successful activity (both
        # verifying and labeling)
	mail_on_success => 0,
	# Send an email after a failed commit activity that the
	# SCM system may overshadow and not report
	# (e.g. Subversion does not report error messages of its
	# post-commit hook.) .
	mail_on_failure => 1,
	mail_settings => {
	    # Must be a valid email address. Can remain empty if
	    # other users should be notified.
	    To => 'replace_with_commit_mailing_list_email@exampledomain.com',
	    # Must be a valid email address. Can remain empty if
	    # mail_also_appears_from_scm_user is enabled.
	    From => 'Scmbug <replace_with_mailing_list_owner_email@exampledomain.com>',
	    # Defaults to localhost if left empty
	    Smtp => 'replace_with_mail_server.exampledomain.com'
	},
	# 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,
	mail_recipients => {
		# Make the email also appear to have been sent by the
		# SCM user.
		mail_also_appears_from_scm_user => 1,
		# List of users that will be notified
		mail_scm_user => 1,
		mail_bug_owner => 1,
		mail_bug_reporter => 1,
		mail_bug_monitors => 1,
		mail_product_owners => 1
	}
}
	      

4.5.2. Bug Resolution

It is possible to automatically change the resolution status of a bug at the time a software change is committed. It is verified that the requested resolution status is a valid resolution state in the bug-tracker and that the requested change does not violate the workflow of the bug-tracker. For example, changing a bug resolution in Bugzilla from REOPENED to UNCONFIRMED is an invalid status change.

Changing resolution status is accomplished if a resolution template expected by Scmbug is identified in the log message. The resolution does not need to apply to the same bug the software change is applied against. It could be applied to a different bug, multiple bugs, or multiple different resolutions could be applied to multiple different bugs. The resolution template must be specified on a separate line on its own and is completely removed before the log message is identified.

Four regular expressions describe how the bug id, the new status, the status resolution, and the status resolution data will be identified. These are defined as part of the resolution_template policy variable as shown in Figure 4-24, through the variables resolution_bugid_regex, resolution_status_regex, resolution_status_resolution_regex, and resolution_status_resolution_data_regex.

A way to split a list of multiple bug ids into separate ids is also described with a regular expression through the variable resolution_bugid_split_regex. An example log message accepted by these expressions is shown in Figure 4-26.

# Resolution template.
#
# Regular expressions that describe how a resolution status
# for a list of bug ids can be identified
resolution_template => {
    enabled => 1,
    # The resolution_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
    resolution_bugid_regex => 'status\s*([\d|\s|,|#]*?):',
    # The resolution_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/
    resolution_bugid_split_regex => ',\s?#|\s?#|,|\s+',
    # The resolution_status_regex is a regular expression that
    # must set the unnamed variable $1 to the requested
    # status. It is checked for a match as: m/$regex/s
    #
    # For example, if one issued in the log message the
    # resolution command:
    #
    # status 547: reopened
    #
    # Then the resolution_status_regex is expected to match
    # "reopened"
    resolution_status_regex => 'status.*?:\s*(\S+)\s*.*',
    # The resolution_status_resolution_regex is a regular
    # expression that must set the unnamed variable $1 to the
    # requested resolution. It is checked for a match as:
    # m/$regex/s
    #
    # For example, if one issued in the log message the
    # resolution command:
    #
    # status 547: resolved fixed
    #
    # Then the resolution_status_resolution_regex is expected
    # to match "fixed"
    resolution_status_resolution_regex => 'status.*?:\s*\S+\s+(\S+)'
    # The resolution_status_resolution_data_regex is a regular
    # expression that must set the unnamed variable $1 to the
    # additional data supplied by the resolution status. It is
    # checked for a match as:
    # m/$regex/s
    #
    # For example, if one issued in the log message the
    # resolution command:
    #
    # status 548: resolved duplicate 547
    #
    # Then the resolution_status_resolution_data_regex is
    # expected to match "547"
    resolution_status_resolution_data_regex => 'status.*?:\s*\S+\s+\S+\s+(\S+)',
    },
	    

Some bug-trackers may report resolution-related information with a token that contains spaces. For example, Mantis 1.0.0 offers the resolution "unable to reproduce". This would make it difficult to develop regular expressions that will correctly identify the new status and resolution. This resolution could instead be written in a log message by the user as "unable_to_reproduce" and have Scmbug configured to replace all underscores ("_") with spaces (" ") using the resolution_status_convert policy, as shown in Figure 4-25.

    # The resolution_status_* information can have all of the
    # following characters converted according to a regular
    # expression. This is useful in addressing the limitation
    # of some bug-trackers that report a resolution-related
    # information with a token that contains spaces. For
    # example:
    #
    # "unable to reproduce" in Mantis.
resolution_template => {
    resolution_status_convert => {
	enabled => 0,
	# Regular expressions that will be applied to convert
	# the characters of all resolution_status_*
	# information. It is applied for substitution as:
	#
	# s/$convert_from/$convert_to/g
	resolution_status_convert_from => '_',
	resolution_status_convert_to => ' '
	},
}
	    

This template can be customized when the Scmbug codebase is configured, prior to installation. The arguments --with-resolution-template-bugid-regex=<regular_expression>, --with-resolution-template-bugid-split-regex=<regular_expression>, --with-resolution-template-status-regex=<regular_expression>, --with-resolution-template-status-resolution-regex=<regular_expression>, --with-resolution-template-status-resolution-data-regex=<regular_expression>, --with-resolution-template-status-convert-from-regex=<regular_expression>, and --with-resolution-template-status-convert-to-regex=<regular_expression> can be passed to configure, shown in Figure 8-4.

status 548,622: reopened
status 755: resolved worksforme
bug 547:Implemented automatic status resolution as a new policy. This seems
to work but will need improvements in the testsuite.
status 547: REsolved fIXED
status 548: RESOLVED duplicate 547
status 647: assigned unassigned@mkgnu.net
	    

The resolution status and resolution descriptions are verified case insensitive by default, as shown in Figure 4-26. This can be controlled using the resolution_status_case_sensitive_verification variable, as shown in Figure 4-27.

    # Apply a case sensitive resolution and resolution status verification
    resolution_status_case_sensitive_verification => 0,
	    

A resolution description must refer to bug ids filed against the SCM system's associated product name in the bug-tracking system. This behavior is optional and can be configured in the glue configuration file using the resolution_valid_product_name policy variable, as shown in Figure 4-28.

resolution_template => {
    # The bugs whose resolution status will be changed must be
    # filed against a valid product name.
    resolution_valid_product_name => 1,
},
	      

The SCM user issuing a bug resolution must be the owner of the bug against which subsequent integration requests will be issued. This behavior is optional and can be configured in the glue configuration file using the resolution_valid_bug_owner policy variable, as shown in Figure 4-29.

resolution_template => {
    # The SCM user must be the user to which the bugs whose
    # resolution status will be changed are assigned
    resolution_valid_bug_owner => 1
},
	      

4.5.3. Autolinkification

There are plans to support autolinkification.

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 integration has only been verified to work with a :pserver: configuration. A CVSROOT starting with :local: does not work. This is because of the presumptious way CVSNT handles the CVSROOT variable. Apparently for some configurations it expands it to include the configuration type. The integration hooks use this expanded variable and as a result are pointed to incorrect paths.

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 ?

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 activities are issued using the same log message. Duplicate log messages are then entered in the bug-tracking system. Scmbug solves this problem by using the commitinfo and loginfo hooks to detect commits in separate directories and consolidate the log messages entered in the bug-tracking system as one log message (one integration activity). This behavior is optional and can be configured in the glue configuration file using the consolidate_cvs_messages variable, as shown in Figure 7-6. However, ActiveState ActivePerl does not yet implement the getppid() function. Windows systems running Scmbug need to disable consolidate_cvs_messages.

# This applies only to CVS. When a commit affects more than
# one directory, multiple duplicate log comments are inserted,
# one-per-directory. Enabling this option would consolidate
# the commits to all use the first log message.
consolidate_cvs_messages => 1
        

7.1.2. Subversion

Subversion repositories do not support installation of the integration glue remotely. Local repository access is required.

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

Subversion does not distinguish between commit activities and creation of tags or branches. It recommends that the user manually creates top-level directories named /trunk, /tags and /branches. When it's time to create a tag or branch, Subversion proposes following the convention of creating a copy of the main trunk using 'svn copy' in the /tags or /branches directories. As a result, the glue must manually detect if an activity_verify issued by Subversion also implies an activity_tag. To do so, it checks for addition of new subdirectories in the directories /tags or /branches. This behavior is defined in the glue configuration file using the label_directories variable, as shown in Figure 7-7.

# This applies only to Subversion. It is recommended that tags
# are stored in the 'tags' directory, and branches in the
# 'branches' directory.
label_directories => [
		      'tags',
		      'branches'
		      ]
	

Similarly, Subversion does not distinguish between the main development line and other branches. The glue must manually detect if a changeset is committed under /trunk. This behavior is defined in the glue configuration file using the main_trunk_directories variable, as shown in Figure 7-8.

# This applies only to Subversion. It is recommended that the
# main trunk work is stored in the 'trunk' directory.
main_trunk_directories => [
			   'trunk'
			   ]
	

It is not mandatory that trunk, tags, and branches are created in the root of the repository. A more flexible directory structure can be defined using the product_name_definition variable as shown in Figure 4-17.

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.

If you believe your system meets the package dependencies, but installing packages fails due to missing dependencies, installation of the packages is still possible. Installation of RPM packages can be forced as shown in Figure 8-2, and installation of Debian packages can be forced as shown in Figure 8-3. Figure 8-2. Forcing installation of RPM packages. bash$ rpm -ivh --force --nodeps <RPM_PACKAGE_NAME> Figure 8-3. Forcing installation of Debian packages. bash$ dpkg -i --force-depends <DEB_PACKAGE_NAME>

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-4 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. It is also possible to build the system without documentation. If you are configuring from source code, running './configure --help' can provide more information.

	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 <