4.4. 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.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.

Figure 4-3. Glue enabling variable.

#
# 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.

Figure 4-4. Paths to the SCM tool's binaries.

# 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.

Figure 4-5. Regular expressions describing the bug id, the split of bug ids and the log message body.

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.

Figure 4-6. Example log message accepted.

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.

Figure 4-7. Minimum log message size policy.

# 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.

Figure 4-8. 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]_.+$'
	      ]
	  }
	    

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.

Figure 4-9. 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.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:

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.

Figure 4-13. Disabling SCM to bug-tracking username 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.

Figure 4-14. Disabling case sensitive SCM to bug-tracking username verification.

# 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.

Figure 4-15. Valid product name policy.

# 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-6, for Mail on success and for Autolinkification. It can be specified in the glue configuration file using the product_name_definition policy variable in two ways:

4.4.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-20.

Figure 4-20. Valid bug owner policy.

# 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.

Figure 4-21. Anonymous SCM username policy.

# 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.

Figure 4-22. Open bug state policy.

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