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.
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 3.
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. 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.
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 5, 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 6.
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*(.*)'
},
|
Figure 5. Regular expressions describing the bug id, the split of bug ids and the log message.
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 2 in the Section called System in the chapter called Resources.
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.
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 7.
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 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]_.+$'
]
}
|
Figure 8. Label naming convention policy.
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 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'
},
|
Figure 9. Presence of bug ids policy.
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 10.
# 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 => '' },Figure 10. SCM to bug-tracking username mapping based on mapping_ldap.
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 11.
# 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' } },Figure 11. SCM to bug-tracking username mapping based on mapping_regexes.
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 12.
# 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' } },Figure 12. SCM to bug-tracking username mapping based on mapping_values.
If the SCM username already matches the bug-tracking username, these mappings can be disabled. 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.
The username mapping is applied case sensitive. This can be configured in the daemon configuration file as shown in Figure 13. 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 mapping_case_sensitive to be disabled.
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 14.
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 15 shows a configuration example that can autodetect from the repository structure of Figure 16 the list of product names in Figure 17. When a file from one of the directories shown in Figure 16 is commited, the appropriate product name shown in Figure 17 will be autodetected.
# Valid product name. 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. valid_product_name => { enabled => 1, type => 'auto', value => 'dir/prefix1/productMain_(.+?)/,dir2/(.+?)/,dir3/(?:trunk|tags|branches)/(.+?)/' },Figure 15. Automatically detected product name.
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 16. Repository structure with product names that can be automatically detected.
subproductA subproductB productA_3-1 productB productB_multiuser productC
Figure 17. Automatically detected product names from Figure 16.
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.
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 18.
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 19.