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. Some others are performed on the server side, the machine hosting the Scmbug daemon.
4.2.1. Glue Checks
An integration request is issued to the Scmbug daemon if the following checks, performed by the glue, succeed.
4.2.1.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.1.2. Use of 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-2, 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-3.
Figure 4-2. 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.*?:(.*)'
},
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.1.3. 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.1.4. 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-4.
4.2.1.5. 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-5.
Figure 4-5. 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.2. Server Checks
When an integration request is received by the Scmbug daemon, the following server checks are performed.
4.2.2.1. 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-6.
Figure 4-6. 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.2.2. 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-7.
If the SCM username already matches the bug-tracking username, the mapping can be disabled.4.2.2.3. 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 is defined in the glue configuration file using the product_names policy variable, as shown in Figure 4-8.
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 will accept multiple product names to accomodate this scenario, as shown in Figure 4-9. In this case, an activity_verify integration request must refer to bug ids filed against at least one of the SCM system's associated product names in the bug-tracking system.
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.
The downside of using multiple product names is that labeling operations will not be integrated, since the glue cannot determine which product is being labeled when a tag or branch is created. No activity_tag integration requests are issued from the glue to the daemon when multiple product names have been specified.
Figure 4-9. Multiple product names.
# If only one product name is supplied, each bug id supplied # during commit messages must be filed against this product # name. Labeling operations are also integrated. # # If more than one product name is specified, each bug id # supplied during commit messages must be filed against at # least one of the product names. This comes at the expense of # no longer integrating labeling operations. # # This policy is ALWAYS enabled product_names => [ 'Product_Standard', 'Product_Professional_Edition', ]
 | 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. |
4.2.2.4. 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-10.
4.2.2.5. Open-bug-state
The bug against which an activity_verify integration request is issued must be in an open, active state in the bug-tracking system.
4.2.2.6. 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-11.
Figure 4-11. Mail on success policy.
# Send an email after a successful activity (both committing
# and labeling).
mail_on_success => {
enabled => 0,
# 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 => {
# Must be a valid email address
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'
}
}