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.
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.
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.
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.
The log message supplied to the SCM system when committing a software change is verified to include only distinct bug ids.
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.
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.
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' },
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.
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.
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-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. |
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.
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' },
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.