Jira bug report template

Write the summary as where, then what

Not enough	Good
Checkout broken	Checkout: discount code is applied twice after the page is refreshed
Export not working	Orders CSV export: order dates are one day early for orders placed after 23:00
API error	POST /api/invoices: returns 500 when the customer has no billing address

The description template

Copy everything in the box into the Jira Description field. Replace each <hint> with the answer. Write none or unknown rather than deleting a line, so readers know you checked.

Repository: <which repository the fix belongs in, or "n/a" if the project has only one>
Where: <page and URL path, API endpoint and method, app screen, background job, command or function>
Environment: <staging, production or local; browser or device and OS for a UI bug>
Version: <app version, build number or commit where you saw it>
Last worked in: <version or date it last worked correctly, "never worked" or "unknown">
Logged in as: <role and permissions, e.g. "customer, no admin rights">
Settings and flags: <feature flags, account settings, language or time zone that matter, or "none">
How often: <always, or e.g. "3 of 5 tries, more often right after login">

Starting state and test data:
<everything that must exist before step 1, with exact values; made-up data only>

Steps to reproduce:
1. <first action, from the starting state above>
2. <next action, with the exact value typed, clicked or sent>
3. <the action where it goes wrong>

Actual result:
<what happened, with exact values and the exact error text>

Expected result:
<what should have happened, with exact values>

Why this is expected:
<quote the requirement or acceptance criteria, or name the version that behaved correctly>

Error output:
<error message, first lines of the stack trace, console errors, the failing request and response; tokens and passwords removed>

Notes:
<optional: when it does NOT happen, a workaround, a suspected cause>

A filled-in example

Summary: Checkout: discount code is applied twice after the page is refreshed

Repository: acme/shop-web
Where: checkout payment page, /checkout/payment; API POST /api/cart/discount
Environment: staging; Chrome 128 on macOS 14, same in Firefox 130
Version: web 2.14.0, commit 3f9c2ab
Last worked in: 2.13.2
Logged in as: any customer account, no admin rights
Settings and flags: new-checkout flag on
How often: always (5 of 5 tries)

Starting state and test data:
Empty cart. Product "Blue T-shirt" priced €100.00.
Discount code SAVE10: 10% off, one use per order.

Steps to reproduce:
1. Add one "Blue T-shirt" to the cart.
2. Open /checkout/payment.
3. Type SAVE10 in "Discount code" and click Apply. The total shows €90.00, which is correct.
4. Refresh the page.

Actual result:
The total shows €81.00. The order summary lists "SAVE10 −€10.00" and "SAVE10 −€9.00".

Expected result:
The total stays €90.00 and SAVE10 is listed once. Refreshing must never apply a code again.

Why this is expected:
Acceptance criteria of SHOP-812: "A discount code applies at most once per order." 2.13.2 behaves correctly.

Error output:
No console errors. On refresh the page sends POST /api/cart/discount again:
Request:  {"code":"SAVE10"}
Response: 200 {"total":81.00,"discounts":[{"code":"SAVE10","amount":10.00},{"code":"SAVE10","amount":9.00}]}

Notes:
Does not happen when you leave checkout and come back through the cart.

What makes a bug reproducible

• Exact values, not impressions. "Total is €81.00, expected €90.00" can be turned into a test. "Total looks wrong" becomes a question.
• A starting state anyone can recreate. Describe the record you used, its fields and values, instead of "order 48213 on production".
• What outside services sent back. When a payment provider, email service or other third-party API is involved, paste the exact request and response.
• When it does not happen. "Only with two or more items" or "not in Firefox" narrows the cause fast.
• Text, kept intact. Paste logs, stack traces and JSON into a Jira code block so their lines survive. Only the lines around the error, not the whole log.
• Made-up data, never secrets. The example often ends up in a test in your code. Never paste passwords, API keys, tokens or session cookies; replace them with <removed>.

Checklist before you file

• One bug, fixable in one repository. When the web app and the API both need changing, file one Bug for each.
• The Summary says where it happens and what goes wrong.
• Someone who has never seen the bug can follow the steps without asking you anything.
• Actual and expected results give exact values or messages.
• The test data is written out and made up; nothing depends on production data or a real login.
• Errors, logs and requests are pasted as text. Nothing important lives only in a screenshot, link, table or other field.
• It is something the product does wrong today, not a feature request, a question or a duplicate.

Using the template with Label2Prod

Label2Prod reads the Summary, Description, Components and comments of an issue, as text. It does not open attachments, follow links to other tools, or read other fields such as Environment or custom fields. That is why the template puts everything in the Description: paste the error message and the requests there, and attach screenshots for people as well.

When a Jira project is connected to more than one repository, name the repository in the Repository: line or pick a Component named after it. Then add the autofix label. If something is still missing, Label2Prod asks in a comment on the issue; reply with a new comment and it carries on.