Crafting the Perfect Bug Report – Make Your Issues Count

On a recent project, I ran into an issue where two unit tests would pass or fail depending on the order we ran them. This inconsistency pointed to a deeper problem. After some investigation, my team and I unearthed a bug in Prisma. It turned out that it was an issue with significant and sneaky impacts. So, we knew an effective bug report would get the issue noticed and resolved quickly. Here’s what I learned along the way about creating actionable bug reports and why this skill is so vital in a development career.

The Importance of Actionable Bug Reports

In open-source projects, maintainers often juggle multiple tasks and have limited time to address issues. An effective bug report can mean the difference between a quick fix and a prolonged, frustrating debugging process. Clear, concise, well-documented reports enable maintainers to understand the problem swiftly, and then replicate and address it without wading through ambiguities.

To illustrate, related bugs had been reported to Prisma before, but due to their vague and less narrowed-in presentation, they didn’t get quick acknowledgment. By providing a well-constructed report, you’re helping yourself and contributing to the health of the tool and community.

Isolating and Reporting the Bug

This is the most important part of the process. It can be painful to figure out how to wrap up whatever vague, difficult-to-replicate issue you’re seeing in an isolated instance. Regardless, taking on that pain will make it immensely easier for the maintainers reviewing issues and make it more likely your issue will actually be prioritized. Always try to create the most minimal, reproducible example before even starting the issue-reporting process. Including workarounds and expected behavior are good further guides to help approach a fix.

Key Elements of an Effective Bug Report

Here is a breakdown of how I structured my bug report. An actionable report should include the following elements:

1. Clear and Descriptive Title: The title should offer a succinct but urgent summary of the bug. Describe what the overarching problem is (if you know), not just the symptoms. For the Prisma bug report, we went with

Prepared statement caching is data dependent on numeric input parameters.

2. Bug Description: Provide a detailed yet concise description of what you encountered. Including any related issues is also a great idea for providing more context and giving a bump to any existing awareness of the issue.

When I run a raw query with a numeric parameter, the sequence of values for that parameter can cause error 22PO3 - incorrect binary data format.

**Related issue:** #16611

3. Steps to Reproduce: Outline the exact steps needed to reproduce the issue. Providing easily executable code and clear descriptions of what to look for is the best strategy.

await prisma.$queryRaw(
Prisma.sql`select * from version() where LENGTH("version") > ${1}`
);

await prisma.$queryRaw(
Prisma.sql`select * from version() where LENGTH("version") > ${1.1}`
);

Success cases: Run query with decimal value (1.1) first, then query with integer value. 
Failure cases: Run query with integer value (1) first, then query with decimal value. Throws code 22PO3 - incorrect binary data format.

4. Expected vs. Actual Behavior: Clearly state what you expected to happen and what actually occurred.

Prisma prepared statement caching should not prevent varying numeric types from being passed in as parameters.

5. Environment / Setup / Versions: Include relevant information about your development environment and tool versions.

- OS: macOS
- Database: PostgreSQL
- Node.js version: v18.18.2
- Prisma version: 5.7.1

6. Workarounds (if any): Mention any workarounds you found. This will be especially helpful for any other users investigating the same issue.

- Disabling Prisma's prepared statement cache (`?statement_cache_size=0`) prevents the issue from occurring.
- Manually serializing the input value to a string and then casting to a Postgres decimal type separately prevents the issue from occurring (`${n.toFixed(2)}::decimal`).

Why This Skill Matters

Submitting effective bug reports is a skill that might not be obvious to seek out, especially when starting a development career. However, it can significantly impact the success of a project. Communicating issues clearly and isolating them precisely means quicker resolutions and a smoother development process. It’s a critical part of professional growth that benefits not only your projects but also the broader developer community.