Actionable issue reporting with DeepSource
When using static analysis to automate parts of code reviews, the primary goal is to catch all known issues before the changes go for manual review. An equally important aspect of this process is ensuring that every issue detected is addressed by the team. In practice, however, that's not always the case.
Typically, each issue reported by DeepSource includes information such as a brief description with the file and line location and type of the issue (anti-pattern, bug risk, security, performance, etc.) These details are sufficient if you are familiar with the fix. If not, you need to spend time understanding the issue and finding the fix. When you have an array of things to focus on such as improving existing features, reviewing peer's code, implementing new features — addressing the issues raised by static analysis generally takes a back seat, even if some of them could be critical.
Actionable issue reporting with DeepSource
The accuracy of issues reported is imperative to drive action. Having said that, other factors have a role to play as well. In this post, we will cover the improvements we have made in DeepSource over the past few months to reduce friction that comes in the way of taking action on issues.
- Depth of issues reported
- Autofix to automatically fix some of the issues, in a couple of clicks
- Required checks to block pull requests
An overview of the DeepSource workflow
DeepSource automatically reviews code to find objective errors and improvements. When configured, the analysis triggers on every pull request and commit. With native integration with GitHub and GitLab, when our analyzers finds issues in the changeset, the status is marked as 'Passed' or 'Failed'.
Get all the issue details in one place
All the issues detected by DeepSource are reported under the 'Issues' tab of the repository dashboard.
Each issue has the following information attached to it:
- Title: A one-line description of the issue.
- Issue code: The unique code you can use to refer the issue again or to silence it in your code. (docs)
- Issue type: Based on the impact an issue can have on the code, each one of them is assigned an issue type — bug risk, anti-pattern, performance issue, security risk, to name a few.
- Analyzer: An analyzer operates on source code to detect issues and report metrics. Analyzers can be focused on a programming language, like the Python analyzer, or something generic like the test coverage analyzer.
- Timestamp: When the issue was reported and last seen.
- Occurrences: An issue can occur multiple times across files. Each instance of an issue is referred to as an occurrence.
- Description: Detailed explanation on why the issue is an issue, why it occurred and in many cases, a recommended solution.
- File path and location: File where the issue is reported along with the line and column range that the issue occurrence spans across, highlighted in the code snippet.
How does it help?
DeepSource's detailed reporting focuses on providing enough information to guide you towards the solution rather than leaving you with questions.
- Describes the cause: The description tagged with each issue outlines why the issue occurred and the impact it can have on your code. This also saves you from repeating the same issue in future.
- Directs to the solution: Next, it specifies a recommended solution and/or links to external references, so you can quickly find the solution
- Informed decision making: More details means a better understanding of the issue. This helps you decide faster about what to do next. Is the issue critical? Should you resolve it on priority? Should you wait to fix it later and go ahead with the release now?
Automatically fix issues with Autofix
Well detailed issue reporting provides all necessary context to help you fix the issues. Autofix takes this a step further. It generates the suggested fix to the files and creates a pull-request for your approval.
How does it work?
Look for the 'Autofix' button in certain issues in the Issues tab, view and confirm the suggested fixes and click 'Create pull-request'. A pull-request with fixes for issues will be created directly on your GitHub or GitLab repository.
How does it help?
Autofix provides the exact solution. All you have to do is go through the fixes, and approve them.
One of the primary motivations behind Autofix is, say if there are 50 occurrences of an issue across multiple files. The thought of manually going through each file and making the changes can be demotivating. With Autofix, you can skip this whole exercise and let our analyzers generate the fix for you.
Block pull requests based on issue type
To ensure every team member follows the best practices, it has to be enforced. In the DeepSource dashboard, head to settings and specify the analysis failure conditions — a required check for each repository. This ensures that unless each occurrence of the selected issue type(s) (bug risk or anti-pattern or security issue or all of them) is not resolved (or marked as intentional), the pull request cannot be merged. You can configure them depending on which category of issues matters the most to you. For instance, some teams deprioritize style or documentation issues over others. These categories can be tweaked anytime the team's view changes.
How does it help?
A required check leaves no room for merging the code change without fixing the issues. It guarantees that all the incoming code complies with the team's guidelines. Well, it also makes it easier for the whole team to follow the guidelines, without any overhead.
From the very beginning, DeepSource has focused on ways to encourage developers to fix issues, not just detect them. We will continue to add more features in the future to achieve this vision. To know more about DeepSource, check out our features section. If you would like to go ahead and try DeepSource yourself, sign up with GitHub or GitLab to get started.
