Updated on 2023-07-25 GMT+08:00

Associating Work Items

With CodeHub, you can associate each code commit with a work item of ProjectMan.

  • Associated work items help developers accurately record tasks for fixing bugs and developing new features.
  • Associated work items allow project managers to view information such as change committer and committed content involved in each requirement and bug fixing task.

Work item: It is one of the methods of tracing work contents in ProjectMan. Generally, a work item has a unique number and description. A work item can be a requirement, defect, or task. In the ProjectMan service, a work item is a list of work contents that can be visualized management.

Commit: You can commit and save operations on files in the working directory, including creating, editing, and deleting files. The following shows the commit command, in which the -m parameter is mandatory and followed by the commit message.

git commit -m <commit_message>

On the CodeHub console, a changed file can be saved only after you enter a commit message. Each saving operation on the console is a commit, and the mandatory message corresponds to the content after -m in the commit command.

CodeHub automatically associates work items with code by capturing keywords from the commit message after -m. The most commonly used keyword is fix, which is the recommended keyword in the prompt. The keyword must meet the following format:

git commit -m "fix #<work_item_id> <commit_message>"

If a work item is successfully associated, the system automatically changes the work item status based on the configured code commit status transition. By default, the fix keyword sets the work item to the resolved state.

Example:

git commit -m "fix #123456 fixed this bug"

The work item 123456 is set to the resolved state after being pushed to CodeHub.

CodeHub allows you to associate work items with code on the local host or on the console. The following describes the two methods.

Assume that a project has been created. If no project has been created, create a project by referring to "Creating a Project in ProjectMan". In this case, you need to perform operations in (Optional) Configuring the Code Submission Status, Creating a Work Item, and Create a code repository under the project.

  • Only members of the same project and repository can associate work items with code.
  • For the work item creator, specified modifier, or account (such as Project Manager) that has the permission to modify all work items in the project, their association operations can change the work item status (new or resolved) and generate comment records. In the association records, Transition successful is displayed in the Result column, as shown in the following figure. For other members, only association records are generated. The work item status is not changed, no comment record is generated, and Association successful is displayed in the Result column.

(Optional) Configuring the Code Commit Status Transition

By default, you can use the fix keyword in the commit message to change the work item to the resolved state.

The following describes the working principle and advanced settings of associating work items with code commits. If you only need default settings, skip this section.

In project settings, you can set three commit message keywords (such as fix, close, and resolve) for different work item types (Epic, Feature, Story, Task, and Bug). You can associate each keyword with a target status (for example, Resolved or Closed). The work item status can also be customized.

The default settings of code commit status transition are as follows:

  • The fix keyword is associated with the Resolved target state (enabled by default).
  • The close keyword is associated with the Closed target state (disabled by default).
  • The resolve keyword is associated with the Resolved target state (enabled by default).

Only the project manager or other roles with the project setting permission can modify the settings.

The following describes how to associate the close keyword to Rejected in a Task work item.

  1. Access the project.
  2. Choose Settings > Project Settings and find the code commit status corresponding to the Task work item type, as shown in the following figure.

  3. Click the target status of close, set it to Rejected, and set Apply to .

    The settings are automatically saved.

Then, you can use the close keyword in the commit message to change the status of a Task work item to Rejected when committing code.

Example:

git commit -m "close #<task_work_item_id> <commit_message>"

Creating a Work Item

To compare Associating a Work Item with Locally Committed Code and Associating Work Items with Code Committed on the Console, repeat the following steps to create two Task work items.

  1. Accessing the Project
  2. Choose Work > Work Items.
  3. Click Create Work Item and select Task from the drop-down list. The page for creating a work item is displayed.
  4. Enter a title and click Save.

The work item management page is displayed. You can view the work item ID and the status is New.

In this example:

  • The ID of task01 is 7370149.
  • The ID of task02 is 7370151.

On the project homepage, choose Work > Work Items to obtain a work item ID.

Associating a Work Item with Locally Committed Code

Prepare the Git environment on the local host. For details, see Overview. If you can access the repository (the corresponding remote repository has been associated), perform the following operations:

Create a file in the local master branch and push the file to the remote repository. During the push, use the keyword fix in -m to associate the file with the work item task01.

  • In this example, the master branch is modified to simplify the process so that you can quickly understand how to associate a work item with code committed on the local host.
  • Do not modify the master branch in the actual situation. It is recommended that you create a branch for file operations, merge the changed file into the master branch, and push the master branch to the remote repository.
  1. Right-click the local repository folder and open Git Bash.
  2. Check whether the remote repository address is successfully associated.

    git remote -v          # View the remote repository address associated with the local repository.

    In the following figure, the underlined part indicates the remote repository address associated with the local repository, and the information before the address is the alias of the remote repository on the local computer.

    If the associated repository is not the one you want or the repository is not associated, clone the desired repository to the local computer.

    After the clone is successful, run the git remote -v command again to verify the association.

  3. Check the repository status and switch to the master branch. (Skip this step for a repository cloned in the previous step.)

    git status             # Check the repository status. You can view the current branch and whether there are unsaved, uncommitted, and unpushed changes on the branch.
    git checkout master    # Switch to the master branch. Run the command when the current branch is not the master branch.

  4. Create a file in the local repository folder. In this example, the file is named fileFor7370149.
  5. Add the new file to the staging area using Git Bash.

    git add fileFor7370149

  6. Commit the operation using Git Bash.

    The git commit -m "fix #7370149 Task01" #/ uses the fix keyword to associate task01 whose ID is 7370149.

    61081924 is the ID of tesk-01 created in Creating a Work Item.

  7. Push the committed content to the associated CodeHub repository using Git Bash.

    git push

    If the push is successful, the return value varies depending on the repository structure. If all steps are 100% and done, the push is successful. If the push fails, the key is incorrect.

  8. Verify the association result.

    After the preceding operations are complete, go to the work item list, find the work item whose ID is 7370149, and view its details, as shown in the following figure.

    • The status is Resolved.
    • An associated code commit record is added. You can click the commit ID to view the details.
    • A comment is automatically generated to describe the work item association.

Associating Work Items with Code Committed on the Console

  1. Go to the repository details page.
  2. Create a file, as shown in the following figure. When filling in the remarks, start with fix #7370151. Set other information to any value.

    7370151 is the ID of task02 created in Creating a Work Item.

  3. Click OK. The system performs the following operations on the CodeHub repository:

    Writes content to the new file.
    git add .
    git commit -m "fix #7370151 Task02"

    That is, the system commits the new file and associates it with the task02 work item using the fix keyword in the -m parameter.

  4. Verify the association.

    View the task02 work item.

    • The status is Resolved.
    • An associated code commit record is added. You can click the commit ID to view the details.
    • A comment is automatically generated to describe the work item association.

Viewing the Association Between Commits and Work Items

The following table describes how to view the association between commits and work items.

Table 1 Viewing the association between commits and work items

Scenario

Operation

On the ProjectMan console, locate the committed code based on the work item.

Locate the target project in ProjectMan and go to the work item details page. Click Associated > Code Commit Records. The associated code commit record is displayed. Click the repository node link (the string before the commit message) in the record. Then the code page is displayed.

On the CodeHub console, view the work item based on the association record.

Go to the target repository details page, click the Associated Work Items tab to view the work items associated with code commits. Click a work item ID to go to the details page.