2. How to... : Enable and Use Change Packages
   
Enable and Use Change Packages
Change packages is an AccuRev feature that associates changes made to an element with a specific issue in an issue tracking system; users are required to specify that issue number each time they promote changes out of a workspace. To enable change packages for your Git commits you need to do the following:
• In AccuRev, ensure that change packages are configured on the relevant AccuRev server. See the AccuRev on-line Help, which includes all the current AccuRev documentation. Use the index and search mechanisms in the on-line Help to learn how to configure change packages, and optionally, third-party issue tracking systems (ITS) if you are using something other than AccuWork.
• In GitCentric, specify the ITS you are using and the format of the Git commit message you will require users to follow when pushing commits. You specify this information on the AccuRev Connector panel of the Repositories page as described in this section.
Once you have enable change packages, you must inform your users of the requirement to add comments to their commits in the format you choose. The process for using a regular expression to specify the commit message format is described in the following section.
Specifying the Commit Message Format
To specify the commit message format that users will be required to follow when pushing commits (and from which the GitCentric bridge will obtain the issue number required to enforce AccuRev change packages):
1. Click the Administration button, then click the Repositories menu to display the Repositories page. (See Chapter 5 Administration for reference information.)
2. Click the repository for which you want to enable change packages.
3. On the Repositories page, click AccuRev Connector menu and locate the Associate Issues With Commits section. (Reference information is a available at AccuRev Connector on page 68.)
4. In the Issue Tracking System field, specify whether you are using AccuWork or a third-party issue tracking system.
Tip: If this field is disabled, specify the AccuRev server connection information and click the Save button.
5. In the Regular Expression field, use a regular expression to specify the format of the commit message you require -- Resolves issue 1234, for example. You can accomplish this by either:
• Entering a regular expression.
Tip: GitCentric displays sample expressions as soon as you begin typing in the field, as shown in the following illustration.
• Clicking the Test... button to display a dialog box that lets you experiment and verify that the regular expression you enter satisfies your requirements.
Refer to the instructions on the dialog box for its use.
Clicking the Save button on this dialog box saves your regular expression to the Regular Expression field in the Associate Issues With Commit section of the AccuRev Connector panel.
6. Click the Save button in the Associate Issues With Commit section to save your work.
See About GitCentric Regular Expressions for more information on regular expressions and their use in GitCentric.
About GitCentric Regular Expressions
One of the powers of AccuRev is to associate all of the files affected by a particular change to an issue number tracking that change. This grouping of affected files is called a change package. (See the AccuRev documentation for information about change packages.) If you have change packages enabled on your AccuRev server, either through AccuWork or through a third-party issue tracking system, you may need to enforce the practice of including the issue number in the comment related to Git commits. That is the purpose of the Regular Expression field: to specify a commit message format that users must follow when pushing a change in Git that will be synchronized to AccuRev. The default example provided in the UI (Resolves\s+([\d,]+):) forces users to start their commit messages with “Resolves <issue number>:”. If this is not found, the push will be rejected.
A discussion of Java regular expressions is beyond the scope of this document, but here are examples of what comments would be valid for some of these predefined expressions:
(?:Resolves|Resolved|Fixes|Fixed)\s*((?:(?:US|DE)[\d, ]*)*) -- This format would be useful for the Rally issue tracking system, which makes use of user stories (“US”) and defects (“DE”): The comments can start with “Resolves”, “Resolved”, “Fixes”, or “Fixed”, followed by white space, and then any number of issue numbers prefixed with “US” or “DE”:
Resolves US302, DE1405, US27
Fixed DE12849
Resolved\s+([\d,]+) -- This format would be adequate for simple environments where the comment always starts with “Resolved”, followed by white space, followed by any number of issues, separated by commas:
Resolved 12576
Resolved 34, 149, 11057, 686
Use a search engine and search for “Java regular expressions” for more information about these formats.
Troubleshooting Change Package Errors
Your users may see change package error messages upon a push, and they must contact you as the GitCentric administrator for assistance in rectifying them. Errors are generated when GitCentric synchronizes the push with the AccuRev server, and the AccuRev server encounters a problem with the elements that comprise the change package. You (the GitCentric administrator) must act as a liaison to the AccuRev side of the world, including understanding change package errors and helping your end-users correct them. The following table summarizes some errors you might encounter and what you can do to address them.
Table 5. Addressing Change Package Errors
Error
Problem
Action
Change Package Required
An issue must be included in the commit comments, in the format dictated by the regular expression that was specified when change packages were enabled
Use git commit --amend to effectively rewrite the commit message.
Issue did not meet criteria
Typically means that the commit comment was present and generally formatted correctly, but the state of the AccuWork issue was incorrect (for example, “Completed” instead of “WIP”)
Use git commit --amend to effectively rewrite the commit message.
cpk merge required
Results during parallel development when two users make changes on the same file related to the same issue and one user tries to push his or her changes before pulling the other’s, creating the merge requirement.
To address an existing error, you will need to create a new issue and push changes against it.
To avoid such problems in the future, instead of using a simple git pull, use git pull --rebase to provide serialized commits, avoiding the need to separately merge remote changes in your branch.
Note that if the push command proceeds far enough to scan for issues, it outputs the issue it has detected in the commit message (“Issue(s):” ... for example). If the push command fails, reviewing this output may provide information that can help you troubleshoot any problems with the regular expression that was used to specify the commit message.
For understanding and correcting change package errors that are caused beyond the GitCentric regular expression filter, please consult the AccuRev on-line help, which includes all AccuRev documentation. Use the search mechanism for change package discussions, particularly in the Concepts Guide and Technical Notes.