Writing Better Power BI Pull Request Comments

We've all been there: your colleague sends you their Power BI pull request to approve some changes they've made. You open it up and view the GIT changes and are met with a whole host of files that have been changed! And some files have multiple changes in them. Man! This is going to take days to check and approve!

Why does this happen? Power BI reports generate a lot of metadata noise. Small innocuous changes such as moving a visual can generate lots of line changes in GIT.

As a PR reviewer I know I've sat there transfixed by all the red and green lines trying (and failing) to figure out precisely what has changed. The sheer volume of changes can make it less of a quick check and more of a detective job!

Oftentimes this can lead to the reviewer bringing in the developer to talk through the changes and understand exactly what they are reviewing. Which is a valid approach. However this means two people are now occupied with one task. And time is money...

Here's an idea to help your reviewer and keep the team operating efficiently:

Add Context to the Commit

I have used Visual Studio and Visual Studio Code to do source control. Both these applications allow for you to add a message to any commits you make:

What I tend to do is add brief comments into the message box describing the essentials of the PR. My format for this tends to be the same each time. I use bullets to list the changes made e.g.

• "Added logic to ensure we use config setting to define day of week for week start."
• "Borders added to all donut charts in report."
• "Addition of new [name of measure] to add to new card on Overview page of report."
• "Measure tweak for calculating the number of sales in the last 12 months."

Advantages of This Approach

This commentary in PRs has a number of advantages.

First and foremost, it is immediately obvious to the reviewer what has changed and therefore saves time and frustration for them during the review process.

Secondly this means that the review process as a whole is slicker and can be done asynchronously thereby freeing up more of the team more often to focus on building and increasing team velocity rather than having to collaborate in explaining and chasing down the changes.

Thirdly, we have created an audit trail / history. This will become far more useful when debugging or auditing the commit history. For instance, if there ever is a problem introduced into a report, with clear commentary, it will be easier to walk it back and find the problematic pull request.

Building a Documentation Culture

This is simply an extension of the commentary tips I mentioned in the previous blog article (Power BI Documentation and Keeping Your Future Self Happy). We now have a budding ecosystem of lightweight documentation at every level:

• Comments inside measures - code level notes
• Comments in Power BI Description Box - model level notes
• Comments in Pull Requests - workflow level notes

None of these require much effort and take minimal time to implement. Over time they will become habitual for the developers and they won't remember a time when it wasn't done! Each one on its own is super useful to the development team. All three together though compound the benefits and really help reduce frustration and accelerate your team's velocity.

Social Proof

In my own experience this came about naturally. I would be on the verge of making a commit and would be running through the changes I had made in my head. I then started to jot this down in bullet form as part of the commit itself. I knew this would help me recall what I had done when the reviewer inevitably wanted to talk about what changes I had made in the PR.

I created this habit as somewhat of a personal safety net but it got adopted as a team-wide approach. This happened because at some point we had a team meeting specifically about pull requests as they were becoming more of a time commitment across the team. Our team lead wanted to align the approach across the team and ensure that none of us took too long to look at PRs but equally that we did a thorough job. It was during this meeting that the Data Architect mentioned my commentary approach and stated that he found this easy to follow and that it made my PRs straightforward to review.

Conclusion

So next time you do a pull request for Power BI, add a one-liner explaining what the change is. This will benefit yourself immediately and your team in the long run. And in a few weeks' time you'll wonder how you managed without.