This topic describes how to enable and to use change packages.
Enable 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 kandoMaintain.
- 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
This section describes how to specify 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):
To specify the commit message format:
- Click the Administration button and then click the Repositories menu.
- Click the repository for which you want to enable change packages.
- On the
Repositories page, click
AccuRev Connector menu and locate the
Associate Issues With Commits section. (For more information, see
AccuRev Connector page).
- In the
Issue Tracking System field, specify whether you are using
kandoMaintain or a third-party issue tracking system.
Tip: If this field is disabled, specify the AccuRev Server connection information and click the Save button.
- 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.
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.
- Entering a regular expression. GitCentric displays sample expressions as soon as you begin typing in the field, as shown in the following illustration.
- Click the
Save button in the
Associate Issues With Commit section to save your work.
See GitCentric Regular Expressions for information on regular expressions and their use in GitCentric.
GitCentric Regular Expressions
One of the strengths 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
kandoMaintain 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:
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
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
This section contains troubleshooting techniques for change packages.
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.
|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 kandoMaintain 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: 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, search the online help.