Engineering Workflow Management Code Review

Last updated: October 2nd, 2023
Build basis: Engineering Workflow Management 7.0.3

This article presents Engineering Workflow Management (EWM) code review, which was first released in version 6.0.1 and revamped in 7.0.1. It highlights the capabilities of the tool, how to configure it for your projects, and how to leverage other capabilities built into EWM to ensure that you have an effective code review process that is streamlined and efficient for your development team.

Code inspections can yield more bugs on average than testing, more bugs are found per hour when compared with various testing methodologies, and it’s inexpensive. Code review is ranked among the top three methodologies for finding bugs with only high volume beta testing and modeling or prototyping being ranked higher. Code review averages about twice the yield of traditional test methodologies such as unit, function, system, and integration testing.

There are other benefits of code reviews aside from finding defects. The practice leads to better compliance to coding standards, improved clarity, and better documentation. When you have multiple people reviewing code it tends to promote code reuse, gives team members exposure to different areas of the code, and improves overall team coding skills.

Some teams conduct informal lightweight reviews such as pair programming, over the shoulder reviews, or simple email exchanges between peers. On other teams, code reviews can be highly formalized systematic reviews. In regulated industries with very low tolerance to defects, deep and exhaustive reviews is essential. Consider avionics and automotive industries where defects in mission critical code can result in serious injury or death.

How do software development teams ensure that effective and efficient code reviews are conducted for their projects? Some considerations when selecting a code review tool and methodology include whether teams are co-located or dispersed geographically, the degree of formality in their review process, the need for traceability and auditability, the ability to manage review findings, and developer preferences.

The following sections provide an overview of the features of EWM code review, introduces EWM concepts and terminology for readers who are not familiar with EWM, and provides an overview of the components of the code review tool. Next there are instructions for project administrators on enabling code review for their projects and some optional process advisors (aka preconditions) to help you ensure compliance to your review process. Finally, there is a description of the code review work flow – how to start a review, manage issues and code changes during the review, and complete a review.

Code review features

Code review is integrated with EWM work items and Jazz SCM to provide developers with a seamless, low overhead work flow that is simple to use and is a natural extension to their daily activities. There isn’t a separate server installation, additional licensing fees or other costs associated with using EWM code review. Enabling code review for your projects is simple and takes only a few minutes to set up.

Reviewers can annotate specific lines of code, which helps developers quickly see and fix issues. Issues (or findings) can be marked as must-fix and the reviewer can accept or reject the changes. When preconditions are enabled, a code review cannot be approved if must-fix issues have not been resolved to everyone’s satisfaction.

Developers don’t have to worry about the intricacies of issue management because this is handled for them. Each issue has its own discussion thread and events are logged as the review progresses. Whenever an issue is updated, a new issue raised, or new code changes are added to the review, the events are logged so that you have a complete history of the review life-cycle. Because code reviews are iterative and can include code changes during the review cycle, any annotations on lines of code (issue markers) are automatically re-positioned and visual cues are provided to the reviewer so that they can easily see what has changed since they last looked at the code or since they last reviewed issues.

Team collaboration is accelerated through real-time notification of pending reviews, issues, and fixes. This is becoming more and more important as the number of globally distributed development teams increase. In fact, with the EWM development team spread across three different time zones, it is common for them to have code changes that were written in one time zone reviewed by team members in another time zone.

Code review enables auditing for compliance. Issue status at delivery, approval information, the event logs, and other information captured during the review can be used for a variety of metrics and reporting requirements.

Since the introduction of code review in 6.0.1 more features have been added. Reviewers can inspect intermediate before and after file states which is useful in advanced SCM workflows encountered when multiple developers are working on a common code base.

The ability to extract work items is useful when an issue needs to be addressed but shouldn’t prevent delivery of the current code changes. The extracted work item captures the required work and will have its own code review cycle.

A new command is available to export code review data such as issues raised, issue activity, reviewer information, code delivery status, and other metrics in JSON or XML format. This enables customers to use their existing reporting tools or custom scripts for auditability and other reporting requirements.

Need to add points for new features since 7.0.1 and work in different workflow. This includes process control and enablement, reviewers as part of code review, code review lifecycle.

Each code revies has a lifecycle to clearly indicated which stage of the review process the code review is currently in: Pending, Submitted, In Revision, Approved or Closed.

Reviewers are modeled as part of the code review itself in order to participate properly in the code review lifecycle.

Each project area can configure various aspects of Code Reviews such as issue types, issue resolutions, issue tags and lifecycle preferences

Code reviews are process enabled to allow customization of the code review process.

Concepts and terminology

This section is intended for users who are new to EWM. The concepts and terminology presented here can help with your understanding of the work flows that are described later on in this article. For more information about EWM see Engineering Workflow Management Documentation.

The work item is the mechanism in EWM to track and coordinate development tasks and workflows. You can create your own custom work items but there are several that come out of the box when you install EWM. The common work items that developers typically work on are defects, tasks, and enhancements.

As the developer makes changes to files, he collects them up into a change set –a change set is an object that collects a related group of file or folder changes. The action of adding a change to a change set is called check-in. The developer can continue to make changes to the same or other files and check them into the change set. During this time the change set is active (or open).

After the developer has finished his code changes he completes (or closes) the change set. No more changes can be made or added to the change set. If he discovered that he needed to make more changes he adds the new changes to a new change set. So effectively, a work assignment can result in one or more change sets.

Next, the developer associates the change set(s) to the work item that was assigned to him. If code review has been enabled for his project, the developer sees the code review presentation on the Code Review or Approvals page of the work item. After the required approvals are in place, the developer can share the changes with team members by delivering the change sets to the team’s development stream. Other team members can accept the changes into their own workspace.

Code review components

Code review consists of several components: the EWM work item, a code review overview page, a compare editor for reviewing code changes and annotating lines of code with issues, and an issue editor for describing and discussing issues. Each project area also has a Code Review section for configuring how code review works for the work items of that project.

Work item code review tab

Figure 1 shows the Code Review tab of a work item. The code review presentation can be added to its own tab, as shown in figure 1, or can be added to an existing tab as desire. It is recommended that you configure your project area so that the code review presentation is displayed in its own tab. However, the location of this presentation is entirely up to the project administrator.

In the code review tab you can see the target stream where the changes will be delivered, the associated change sets, and a summary of issues. From the issues section, you can navigate directly to an issue of a file in the code review editor.

Figure 1: Work item code review tab

If you click the Open Code Review the code review page opens (shown in figure 2 and figure 3).

Code review page

The code review page consists of 2 tabs: the Overview tab and the Review tab.

Overview tab

Figure 2: Overview tab

The code review overview tab, shown in figure 2, provides an overview of the state of the code review as well as allowing users to change the stream and reviewers for the code review.

Review tab

Figure 3: Review tab

You can use the compare editor to view before and after states of the source code. On the left is the before state, and on the right is the after state showing the file with the change sets applied. The before and after states are selected by default to be the initial file state and the final file state with all of the change sets applied respectively. However, you can use drop down menus to select intermediate file states to view what changed between two versions of the file.

To the far left is the navigator panel that is used to browse files and issues. Bold font is used to highlight files or issues that have not yet been viewed by the user since the file or issue was last updated.

When you click on a file it is opened in the compare editor, and clicking on an issue opens the issue editor as shown in figure 4.

Code review issue dialog

Figure 4: Issue editor

Issues can be opened on a line of code or you can create general issues associated with the overall changes sets under review. For example, you can raise a general issue to remind the author to include a copyright statement in all files. In our example, an issue has been opened on line 130. Clicking on an issue in the compare editor or navigator panel opens the issue editor. When the issue editor is open, the selected issue is highlighted in the compare editor as shown in our example. Also, an issue icon is positioned beside the line in the compare editor so that you can easily identify where in the code issues have been raised. Hovering over an icon displays the issue ID and summary and, in the event that multiple issues were raised on the same line of code, you see a list of issue IDs and summaries.

When an issue has been addressed, the author marks it as resolved. This action triggers an event that sends an email notification to the reviewer. Note that all actions that change the state of the review, including the addition of change sets, new issues raised, comments, and must-fix/resolution state changes, are logged in the issue editor so you can view its activity history and enable reporting.

Code review lifecycle

A code review involves two primary roles – an author and one or more reviewers. EWM work items and code review are loosely coupled but work items are integral to the code review process. The individual who is the owner of the work item is generally the person making the changes, adding the change sets to the work item, and ultimately delivering the changes to production. This person is considered the author.

Reviewers are added to the code review when it is submitted for review or later, on the Code review overview pane. Reviewers inspect the changes to look for potential defects and to ensure compliance with their team’s coding standards. But anyone with the appropriate permissions (project area/team area) can review the code and raise issues – this ability is not limited to approvers. Nonetheless reviewers are distinguished by the fact that they are ultimately responsible for approving or rejecting the code changes. They have a formal stake in ensuring code quality, compliance to standards, security, etc. of the software that makes its way into production.

Code reviews are iterative – there can be multiple coding-review-fix cycles during a code review before the changes are ready to be delivered to production. Change sets are typically added during the review cycle. Both reviewers and authors are notified whenever change sets are added, new issues are raised, and exiting issues are resolved or commented upon.

Let’s have a look at the key aspects of performing a code review – how to start a review, manage issues and changes, and complete a review.

Starting the review

After the author has finished making code changes and has satisfied any other requirements that your organization has (for example, static analysis, unit testing, etc.) then the author is ready to submit the code for review. Before submitting code for review, the author must complete the following steps:

One or more change sets are checked in and complete.
The change sets are associated to a work item.
One or more reviewers have been added to the code review.
The target stream where the code will be delivered has been specified.

Steps 1 and 2 are typically performed independently of code review; step 3 and 4 can be performed in the web client but are also performed in a wizard in the rich client when the Submit for Review action is triggered in the code review presentation of the work item. Because EWM is flexible and can be customized to your method of working, there is more than one way to meet the above requirements. The next section describes a recommended work flow.

Author submits changes for review

In this example we are using the Eclipse client. A similar workflow could be followed in the web client.

In the Eclipse client the author creates one or more change sets.
When the code changes are ready for review, in the Pending Changes View, right-click on the change sets; then, click Submit for Review…. Note that this action is also available in the core review presentation of the work item, as shown in figure 5.

Figure 5: Submit for review action

In the Submit Changes for Review wizard, complete the following steps:
1. Provide a target stream. The wizard tries to populate the stream as best it can but you should verify that the stream is correct or pick one, if the wizard was unable to find a suitable default.
2. Add one or more reviewers. In this example, Deb is added as a reviewer.
3. As an option, you can provide a submit comment.
4. Click Finish to submit your changes.
5. Note: If you did not check-in your change sets, you are prompted to check them in now, in order to submit them for review. Also, your change sets will be completed for you if they weren’t already.
6. Reviewers are notified by an email that they have been asked to perform a code review. The author can sit back and wait for notification that issues have been raised.

Figure 6: Submit for review wizard

Note: It is good practice to suspend your change sets when you submit your code for review. This removes the change sets from your repository workspace but preserves it in the repository so that you can perform other work without creating dependencies. Once the review is complete, you resume the change sets and deliver your changes.

Open the work item in the eclipse client and click on the Code Review tab. You can see an overview of the current status of the code review. Since we just submitted the changes for review, the status of the code review is Submitted and the status for the reviewer is Pending.

Figure 7: Code review summary in Eclipse client

From the code review tab of the work item, you can click on the Open Code Review button which opens the page in figure 8. This page show the same information as the presentation in the work item but also has additional details about the code review and also allows reviewers to be added or removed from the code review and for the target stream to be changed.

Figure 8: Code review summary in Web Client

Reviewing changes

Once a work item has been submitted for review, any reviewers will be notified by e-mail that they have been asked to perform a review. The reviewer can click in the link in the e-mail and then select the Review tab of the code review page. When they are ready to start reviewing the changes, they can click the Start button, as shown in figure 9. Starting a review will change the reviewer status and code review status to In Review.

Figure 9: Reviewer starts review

As the reviewer performs the review, they may raise issues in the code review compare editor for defects they have discovered in the code, violation of coding practices, questions they may have about the changes, etc. Once they have completed their review, they can click the Done button to either Return the review to the author to address any issues that were found or Approve the review if there were no issues identified.

Note: When a code review is in the In Review state, new change sets cannot be added to the work item. New changes sets can only be added once a reviewer has either approved or returned the review.

If a code review is returned, the reviewers status changes to Returned and, assuming all reviewers have completed their review, the state of the code review itself will change to In Revision. The author will receive e-mails for each issue raised and when the reviewer is done and, once this occurs, can address any issues and associated new change sets, as required. The author can communicate to the reviewers through the issue as the reviewers will receive e-mails for any comments added to an issue. It may be possible that an issue can be addressed withou a code change, in which case, the issue should be resolved. However, it is more likely that an issue will require a code change, in which case the author should make the required modifications to the code, check-in the changes into a change set, complete the change set and associate the change set with the work item.

When the author has addressed and resolved all the issues and attached any new change sets are required, they can resubmit the code review using the Resubmit button shown in figure 10. This changes the state of any reviewers back to Pending and change the code review state back to Submitted. Any reviewers will receive an e-mail notification that the changes are ready for rereview and they can follow the same process outlines above to review the latest state of the changes.

Figure 10: Resubmit

Completing the Review

If all the reviewers approve their reviews, the code review status changes to Approved. This means that all the required approvals are in and the author has the green light to deliver his changes to the production stream.

It is important to note that this process clearly distinguishes review cycles and provides a “handshake” process between author and reviewers. Change sets are reviewed and either approved or returned. A review cycle is returned if additional changes are required of the author before he is permitted to deliver his changes. When new change sets are added, a new review cycle is started when the auther resubmits with the cycle repeating until the code is finally approved for delivery.

Note: If a new change set is attached to the work item after the code review has become approved, this invalidates the approval and the code review state changes back to In Revision. This is to ensure that the code review applies to all changes attached to the work item. To return the code review to the Approved state, the Authoer needs to either remove the new change sets or resubmit the work item for review. To prevent the above from happening, a code review can be closed. Once a code review is closed, it cannot be reopened and new change sets cannot be added to a work item with a closed code review.

Enable code review and enforce policies

In order to use code review on a project, the project area mist be configured to support it. How to do this is outlines in the on-line documentation: Configuring your project area for code review. This consists of the following tasks.

Please refer to the desired section to learn about how to enable and configure code review for your project.

Conclusion

Engineering Workflow Management (EWM) code review is integrated with RTC work items and Jazz SCM to provide developers with a seamless, low overhead work flow that is simple to use, effective and efficient. EWM code review supports formal or lightweight reviews, and enables effective collaboration regardless of whether teams are co-located or dispersed geographically. A simple user interface allows for easy annotation of lines of code, comparison of before and after files states, and issue management. Traceability and reporting support auditability and metrics to drive continuous improvement.

This article highlights some of the features of EWM code review. It explained the key components of the tool and how to quickly set it up for your projects. It shows how to start a review, manage issues and changes throughout the review cycle, and how to complete the review.

References

Working with the code review tool on the IBM Knowledge Center.

Dashboards and work items are no longer publicly available, so some links may be invalid. We now provide similar information through other means. Learn more here.

Feedback

Was this information helpful?

Yes

No 2 people rated this as helpful.