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.
4.2.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-1.
4.2.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-2. 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.
4.2.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-3, through the variables bugid_regex and log_regex.
A way to split a list of multiple bug ids into separate ids is also described with a regular expression through the variable 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-4.
Figure 4-3. Regular expressions describing the bug id, the split of bug ids and the log message.
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*(.*)'
},
This template can be customized when the Scmbug codebase is configured, prior to installation. The arguments --with-template-bugid-regex=<regular_expression>, --with-template-bugid-split-regex=<regular_expression>, and --with-template-log-regex=<regular_expression> can be passed to configure, shown in Figure 8-1.
4.2.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.2.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-5.
4.2.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-6.
Figure 4-6. Label naming convention policy.
# 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]_.+$'
]
}
4.2.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-7.
Figure 4-7. Presence of bug ids policy.
#
# 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.2.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, as shown in Figure 4-8.
Two types of username mappings are possible. The first is a mapping based on a list of regular expressions that describe how the SCM username will be matched and how it will be transformed, using the mapping_regexes variable. The second is a direct, one-to-one mapping of an SCM username to a bug-tracking system username, using the mapping_values variable. Mappings based on mapping_values can override mappings based on mapping_regexes.
Figure 4-8. SCM to bug-tracking username mapping.
# Translation list of SCM usernames to bugtracking system
# usernames. Mappings based on mapping_regexes are applied
# first. Mappings based on mapping_values are applied second, and
# thus can override a mapping based on mapping_regexes.
userlist => {
# 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'
}
},
# This is a one-to-one mapping of SCM usernames to bugtracking
# system 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'
}
},
}
4.2.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. The product name can be defined in the glue configuration file in two ways:
Manually specified. All SCM activity in the repository will be integrated against a single product name in the bug-tracker. This requires setting the valid_product_name policy's type to manual and providing a product name in value, as shown in Figure 4-9.
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 directory prefixes under which any SCM activity is accounted against a product name with the first subdirectory's name.
Figure 4-10 shows a configuration example that can autodetect from the repository structure of Figure 4-11 the list of product names in Figure 4-12. When a file from one of the directories shown in Figure 4-11 is commited, the appropriate product name shown in Figure 4-12 will be autodetected.
Figure 4-10. Automatically detected product name.
valid_product_name => { enabled => 1, type => 'auto', value => 'prefix1/of/directory/in/repository/,prefix2/of/directory/in/repository/' },Figure 4-11. Repository structure with product names that can be automatically detected.
prefix1/of/directory/in/repository/product_base/branches prefix1/of/directory/in/repository/product_base/tags prefix1/of/directory/in/repository/product_base/trunk prefix2/of/directory/in/repository/productA_3-1/branches prefix2/of/directory/in/repository/productA_3-1/tags prefix2/of/directory/in/repository/productA_3-1/trunk prefix2/of/directory/in/repository/productB
Figure 4-12. Automatically detected product names from Figure 4-11.
product_base productA_3-1 productB
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.
4.2.10. Valid Bug Owner
It is verified that the SCM user issuing an activity_verify integration request is 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 valid_bug_owner policy variable, as shown in Figure 4-13.
4.2.11. 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. Thes behavior is optional and can be configured in the glue configuration file using the open_bug_state policy variable, as shown in Figure 4-14.
4.2.12. Mail On Success
An email can be send when an activity is accepted. This is defined in the glue configuration file using the mail_on_success policy variable, as shown in Figure 4-15.
Figure 4-15. Mail on success policy.
# 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
}