In almost every organization, team members collaborate to get work done. Software teams typically transition issues between people for different functions like code development, code review, and testing (even if they are all on the same team). When transitioning an issue from one team member to another it’s important to minimize the amount of ramp up required for the receiver to fully understand the issue. Transferring issues can be extremely expensive as it requires time from not only one, but two team members.
Reviewing code, however, is a best practice among software teams. Code review helps distribute knowledge of the code base making the team more flexible, fault-tolerant, and more nimble. Since knowledge of the code base is distributed across the team, no one person is the bottleneck for the team to make progress across the code base.
Code reviews turn individual knowledge into its more powerful cousin: distributed knowledge.
So how can team members easily introduce new issues to other members efficiently? The trick is good issue tracking practices. Well informed issues keep all of the history in one place and enable all team members to view an issue as a dashboard for that item of work. Let’s take a look at five key practices to create this dashboard and minimize transition time between team members.
1. Ensure you have a clear definition of done
A consistent definition of done creates a clear boundary between code authors and code reviewers. Developers will often collaborate during development. This is a good thing and should be encouraged as the team is problem solving. Having clear metrics around what it means to be code complete ensures reviewers have a consistent baseline and quality bar when doing reviews.
That way, when someone gets a notification from Jira requesting a review, they know that the code has been checked in, built, and passes some level of automated testing. This gives the reviewer confidence that their time is being well spent. No one likes reviewing code that breaks the build in heinous ways.
2. Make action obvious: status and assignee
Writing code and reviewing code are two separate operations. Having separate statuses inside of Jira for these two states makes it easy for the rest of the team to see the progression of work. Code awaiting review is known to be checked in, built, and validated by automated testing. That is important to advertise to the rest of the team and business.
Some teams will transition the assignee of the original issue to the code reviewer during review. Other teams prefer creating a custom field called reviewer where they track this information. In the latter method, Jira administrators can add a screen to prompt for a code reviewer when a developer transitions an issue from in progress to in review.
ProTip: Edit the default quick filter “Only My issues” in Jira Agile to assignee=currentuser() or reviewer = currentuser if your team is tracking reviewer in a custom field.
Jira 6.3 makes issue tracking a natural extension of development. Jira’s new workflow triggers make it easy to automate updating issues between states. Jira listens for common developer actions and updates the workflow in Stash, Bitbucket, GitHub, as well as Subversion, Perforce, and Mercurial with Crucible. For example, when the developer creates a pull request Jira will automatically transition the issue from in progress to in review. That way, everyone on the team knows the status of an issue at any given time.
3. Integrate your tools
Jira integrates with the entire Atlassian set of tools as well as many others through the Atlassian Marketplace. When tools are integrated it makes it easier for the reviewer to follow the stream of work from the original developer. All of the assets pertaining to the issue are linked to one place: the issue detail view in Jira.
1. Get Context: Link to Confluence
Many teams use Confluence to track requirements during the ideation phase. When product owners import requirements from Confluence into Jira, Confluence creates a link in each Jira issue back to the page where that requirement was mentioned. If a code reviewer has questions about why a particular feature was implemented, they can easily jump back to the original spec.
Confluence links show up along side issue links in Jira’s links panel.
2. Validate the code – Bamboo
As a reviewer, I want to ensure that the code compiles and passes automated tests for the entire feature area at a minimum. The development panel in Jira 6.2 pulls to build and deployment status so a reviewer knows the code has been built properly.
Using an issue per branch workflow isolates a developer’s changes from the mainline branch. The magic of Bamboo is that it can run the full validation on branch builds without much overhead from the developer or the build and release team. This gives code reviewers confidence that the right tests have been run on the committed code. Paired with Git’s easy branching and merging, this workflow is ideal for teams. Branches can be fully validated with ease before merging into master. Subversion teams also benefit from CI as well. Validate, validate, validate!
3. See the code to review – Stash/Bitbucket/Crucible
Lastly, the code reviewer needs easy access to the code he or she needs to review. The development panel in Jira shows each branch, commit, and pull request for direct access. Reviewers can see important history like pull requests that did not get merged back into master.
Jira’s reach into the code base makes it easy for the reviewer to see the code in question, comment authoritatively and contextually, and transition the issue back to the original developer. Use Stash and Bitbucket for Git and Crucible for Subversion, Perforce, and Mercurial.
4. Use @mentions to keep conversations in one place
Comments in Jira are an excellent way to record collaboration across the team. During development, questions naturally come up. Keeping these conversations inside of Jira rather than in email give the reviewer more insight into the development process.
Using @mentions inside of Jira makes it easy to keep conversations contained within Jira as the external party is notified that their feedback is requested with a link back to Jira. The activity panel keeps a detailed history of the issue making research easy.
5. Make it easy to create the right issues
As developers, we can make it easy for our users to file issues that give us the right information we need to fix an issue. Jira’s flexible REST APIs can be easily integrated into almost any application. That way, the application can upload logs and report critical environment information right to Jira.
Often times getting logs is a difficult and time-consuming process. Developers can easily automate this step and create better issues that are easier to fix. Richer context for the developer makes for better context for the reviewer and more effective review. Start simple. Building a way to record environment information to a predefined Jira issue key the filer enters into your application can be invaluable for debugging.
Also, Jira Capture can automatically add high fidelity screenshots with markup as well as web environment information to Jira issues. Non-technical users can easily create issues that bring rich development information inside of Jira.
Track issues well
Great issue tracking gives a clear dashboard for the code reviewer to use in his or her review of the code. Code review is widely recognized as a best practice in software development. If the team is reporting that code review is too burdensome, check the fundamentals of issue tracking in your organization.
