default work type<\/a> for software project with several required fields.<\/p>\n\n\n\nNote:<\/strong> This workflow works well for us, but every team is different. Some companies don\u2019t use severity<\/em>, others don\u2019t link bugs to sprints, and automation setups vary. Use this as a guide, not as an instruction to follow for all use cases.<\/p>\n\n\n\nTo ensure each bug report is clear, actionable, and complete, make the following fields mandatory when configuring the Bug issue type in Jira:<\/p>\n\n\n\n
\n\n\n\t| Field<\/th> | Description<\/th> | Best Practices<\/th>\n<\/tr>\n<\/thead>\n |
\n\n\t| Summary<\/td> | Short title of the bug<\/td> | Use the \"What\u2013Where\u2013When\" format. Include key info like affected feature, platform, or trigger (e.g., \u201c[Forge] Templates are not applied to the issue on issue creation when they are assigned to the issue types\u201d). Should be descriptive enough to understand the issue without opening the full ticket.<\/td>\n<\/tr>\n |
\n\t| Description<\/td> | Full bug details<\/td> | Full bug details<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n\n\n\n\n\n- Steps to Reproduce<\/strong>
<\/strong><\/li>\n\n\n\n- Actual Result<\/strong>
<\/strong><\/li>\n\n\n\n- Expected Result<\/strong>
<\/strong><\/li>\n\n\n\n- (Optional) Prerequisites<\/strong> \u2013 conditions required before steps (e.g., user has 500+ templates).
<\/li>\n<\/ol>\n\n\n\nLet\u2019s go into more details of each section:<\/p>\n\n\n\n Summary<\/strong><\/p>\n\n\n\nThe summary is the first and often only thing a developer or product manager reads at a glance, especially when skimming boards or release scopes. That\u2019s why we write it as a compressed description of the problem. It should follow a clear \u201cWhat \u2013 Where \u2013 When\u201d structure<\/p>\n\n\n\n TitanApps tip:<\/strong> Summary is the first thing everyone sees<\/strong> – devs, PMs, support, and even customers (via linked portals). It should be clear and concise, ideally under 255 characters (Jira\u2019s limit). We try to write summaries that make the bug self-explanatory, even if someone never reads the description.<\/p>\n\n\n\nDescription<\/strong><\/p>\n\n\n\nPurpose:<\/strong> A detailed breakdown of the problem, including how to reproduce it.<\/p>\n\n\n\nWe use a clear format:<\/p>\n\n\n\n \n- Prerequisites (optional)<\/strong> \u2013 conditions required to see the bug
<\/li>\n\n\n\n- Steps to Reproduce<\/strong> \u2013 written in bullet form
<\/li>\n\n\n\n- Actual Result<\/strong> \u2013 what happened
<\/li>\n\n\n\n- Expected Result<\/strong> \u2013 what should have happened
<\/li>\n<\/ul>\n\n\n\nThis structure can be pre-filled using Smart Templates or added manually. The most important thing is clarity: we want anyone, even someone unfamiliar with the feature, to be able to reproduce the bug based on this description alone. When needed, we also include supporting artifacts: screenshots, short video recordings (e.g., Loom), and logs.They\u2019re easier to grasp than written steps alone. Especially helpful when dealing with visual bugs or bugs that depend on specific UI states.<\/p>\n\n\n\n As one of our QA team members explained, the description should be so detailed and well-structured that a developer doesn\u2019t need to ping QA for clarification. And yet, not so bloated that the main points get lost.<\/p>\n\n\n\n Priority<\/strong><\/p>\n\n\n\nPriority indicates how urgent the fix is. It answers the question: how soon does this need to be addressed?<\/p>\n\n\n\n We typically use categories like Must<\/strong>, Should<\/strong>, or Could<\/strong>. “Must” is used when core functionality is broken, especially if it affects production or delays a release. “Should” covers important but non-blocking issues. “Could” is for things that are minor, cosmetic, or unlikely to be noticed by users.<\/p>\n\n\n\nIn TitanApps team QA usually sets the initial priority, but PMs or team leads can revise it during triage. <\/p>\n\n\n\n Severity <\/strong>(optional, varies by team)<\/em><\/strong><\/p>\n\n\n\nPurpose:<\/strong> Measures the business or reputational impact, regardless of technical complexity.<\/p>\n\n\n\nSome common cases to use Severity<\/strong> when bugs:<\/p>\n\n\n\n\n- Appear in highly visible areas (e.g., product homepage, customer-facing UI)
<\/li>\n\n\n\n - Affect branding (e.g., a typo in the company name)
<\/li>\n\n\n\n - Don\u2019t block the product technically but damage perception
<\/li>\n<\/ul>\n\n\n\nNote: Severity is different from priority. A bug can have high severity (e.g., offensive word on homepage) but low priority if it\u2019s easy to ignore for a few days.For example, a bug that displays a typo in the company name on the landing page may not break any functionality, but it’s still considered high severity.<\/p>\n\n\n\n As we mentioned before, not all teams use this field.<\/strong> In some Jira setups, only priority is tracked or severity is logged in description or labels. In some setups (and in some TitanApps projects), severity is omitted entirely or treated as an internal classification by QA. In others, it’s explicitly configured and used alongside priority.<\/p>\n\n\n\nThe key thing to remember is that these two don\u2019t always align. A bug can be severe but not urgent (if the issue hasn\u2019t reached customers yet), or urgent but not severe (like a minor functional issue that’s blocking a critical release).<\/p>\n\n\n\n Components<\/strong><\/p>\n\n\n\nComponents let us define which part of the product the bug belongs to. For example, Smart Checklist, Smart Templates, or Forge integration. These are useful for filtering issues on boards, assigning ownership, and creating rules that auto-assign bugs to the correct developer.<\/p>\n\n\n\n One challenge we faced early on was deciding whether to use separate Jira projects per app or to consolidate everything under a single project and organize by components. We chose the latter for simplicity, using components to reflect both the product and the platform (e.g., DC vs Cloud).<\/p>\n\n\n\n Purpose:<\/strong> Shows which module or feature the bug affects (e.g., Frontend, Backend, Forge, DC).<\/p>\n\n\n\nTitanApps use case:
<\/strong>We group our bugs by components like Smart Templates, Smart Checklist, Forge, DC. This helps with:<\/p>\n\n\n\n\n- Auto-assignment to the right developer
<\/li>\n\n\n\n - Filtering on boards
<\/li>\n\n\n\n - Analytics and reporting
<\/li>\n<\/ul>\n\n\n\nSprint<\/strong><\/p>\n\n\n\nCritical bugs found during regression testing go straight into the current active sprint, regardless of whether the sprint is “frozen.” Others may be logged into Icebox or scheduled for future work.<\/p>\n\n\n\n Note from TitanApps team: The bug’s inclusion in a sprint is tied more to impact on the release<\/strong> than technical complexity. If the bug is a release blocker, it enters the current sprint immediately.<\/p>\n\n\n\nWhen we use it:<\/strong><\/p>\n\n\n\n\n- Critical bugs – Added to the current active sprint
<\/li>\n\n\n\n - Non-critical bugs – Moved to Icebox\/backlog
<\/li>\n\n\n\n - Bugs from upcoming features – Tagged to the sprint containing the feature work
<\/li>\n<\/ul>\n\n\n\nIf a live release is broken, the bug goes straight into the current sprint, even if the sprint scope is already full. We treat it as an emergency scope.<\/p>\n\n\n\n Labels<\/strong><\/p>\n\n\n\nLabels are flexible tags we use for filtering, visibility, and sometimes automation. These can include support, tech-debt, hotfix-staging, e2e, or specific team tags. They help us slice and dice bugs when doing post-mortems, retrospectives, or sprint wrap-ups.<\/p>\n\n\n\n We often filter by label during sprint retrospectives to see how many release-blockers we had and whether they were caught early.<\/p>\n\n\n\n Environment<\/strong><\/p>\n\n\n\nKnowing where a bug occurred is critical for debugging. At TitanApps, we track whether the bug was found on staging, production, or a local dev environment. If the Environment field isn’t configured in Jira, we include this info at the top of the Description field.<\/p>\n\n\n\n QA often notes variations in bug behavior across environments. For example, a bug might appear only in staging but not in production, or only under a specific feature flag setup.<\/p>\n\n\n\n Best practice:<\/strong>
<\/strong>Include this either in a dedicated Environment<\/strong> field (if configured) or at the top of the Description<\/strong>.<\/p>\n\n\n\nExamples:<\/p>\n\n\n\n \n- Staging \u2013 during QA testing
<\/li>\n\n\n\n - Production \u2013 reported by customer
<\/li>\n\n\n\n - Development \u2013 caught by devs before commit
<\/li>\n<\/ul>\n\n\n\nReporter & Assignee<\/strong><\/p>\n\n\n\nThe Reporter field is filled automatically by Jira and it\u2019s whoever created the issue. The Assignee, on the other hand, can be manually selected or assigned via automation rules. In some cases, we configure auto-assignment based on the selected component. For example, any bug with Smart Checklist as a component can go directly to that module\u2019s lead developer.<\/p>\n\n\n\n In smaller teams, QA may leave Assignee empty and let devs triage issues during standups. In larger setups, auto-assignment becomes essential to avoid things falling through the cracks.<\/p>\n\n\n\n Affects Version \/ Fix Version<\/strong><\/p>\n\n\n\nThese fields are used to track where the bug appeared (Affects Version) and where it\u2019s expected to be fixed (Fix Version). This is particularly helpful when validating releases or conducting QA sign-off.<\/p>\n\n\n\n Not every team uses these fields rigorously. But when used, they provide a clear version trail that helps QA test fixes against the correct builds, especially in release-heavy environments.<\/p>\n\n\n\n Linked Issues<\/strong><\/p>\n\n\n\nWe link bugs to their related Stories, Epics, or other bugs. This gives context: is this bug part of a larger feature rollout? Is it blocking another ticket? Was it caused by a specific change in a Story?<\/p>\n\n\n\n As one QA noted during a team discussion, this also helps support teams trace customer-reported bugs back to their origin, especially when customers reference a broken feature without knowing the underlying implementation.<\/p>\n\n\n\n Attachments (optional but recommended)<\/strong><\/p>\n\n\n\nWe often include:<\/p>\n\n\n\n \n- Screenshots<\/strong> of the bug state
<\/li>\n\n\n\n- Videos<\/strong> (via Loom or screen capture)
<\/li>\n\n\n\n- Logs<\/strong> (if backend error)
<\/li>\n\n\n\n- Sample files<\/strong> (e.g., uploaded config that caused failure)
<\/li>\n<\/ul>\n\n\n\nThe more context we give, the faster the devs can reproduce the issue and avoid bouncing tickets back and forth.<\/p>\n\n\n\n How a Good Bug Report Looks Like – Examples<\/strong><\/h2>\n\n\n\nA well-written bug report is a communication tool. It reduces questions, speeds up fixes, and helps teams track recurring patterns across releases. In our workflow at TitanApps, a good bug report is structured, neutral in tone, and complete enough that developers can take action without back-and-forth clarification.<\/p>\n\n\n\n The best reports follow a consistent internal standard, whether the bug was discovered by QA during regression testing, by a developer working on a feature, or by support relaying customer input.<\/p>\n\n\n\n Here\u2019s what we expect a strong bug report to contain:<\/p>\n\n\n\n 1. Clear and Informative Summary<\/strong><\/p>\n\n\n\nA good summary acts like the headline of a newspaper article. It should let the reader instantly understand what the problem is, where it happens, and (if applicable) when or under what conditions it occurs.<\/p>\n\n\n\n Bad example:<\/strong><\/p>\n\n\n\n\u201cSomething\u2019s broken in the checklist\u201d<\/p>\n\n\n\n Better example:<\/strong><\/p>\n\n\n\n\u201c[Forge] Templates are not applied to the issue on issue creation when they are assigned to the issue types\u201d<\/p>\n\n\n\n This second version immediately tells us:<\/p>\n\n\n\n \n- The functionality affected (Template assignment)
<\/li>\n\n\n\n - The platform (Forge)
<\/li>\n\n\n\n - The condition (Issue creation)
<\/li>\n<\/ul>\n\n\n\nThis clarity allows faster triage, especially when hundreds of issues are open at once. It also improves issue filtering and searching \u2014 something the support team relies on when referencing bugs from customer reports.<\/p>\n\n\n\n 2. Structured Description<\/strong><\/p>\n\n\n\nThe description field carries most of the information \u2014 and it must be easy to scan. At TitanApps, we follow a standardized template that includes these parts:<\/p>\n\n\n\n Prerequisites (optional)<\/strong><\/p>\n\n\n\nConditions that must exist before the bug can be reproduced. These may include account setup, feature flags, data thresholds (e.g., “500+ templates exist”), or user roles.<\/p>\n\n\n\n Steps to Reproduce<\/strong><\/p>\n\n\n\nA simple, numbered list that anyone can follow, even without deep product knowledge. Avoid assumptions or hidden steps.<\/p>\n\n\n\n Example:<\/strong><\/p>\n\n\n\n1. Open any Jira issue of type ‘General’<\/p>\n\n\n\n 2. Click Smart Checklist > Apply Template<\/p>\n\n\n\n 3. Select any saved template<\/p>\n\n\n\n 4. Click ‘Apply’<\/p>\n\n\n\n Actual Result<\/strong><\/p>\n\n\n\nDescribe exactly what happens after the final step. Be specific, and include what\u2019s visible on screen, error messages, or unexpected behaviors.<\/p>\n\n\n\n Example:<\/strong><\/p>\n\n\n\nThe template appears to apply, but nothing is shown in the checklist. No error is displayed.<\/p>\n\n\n\n Expected Result<\/strong><\/p>\n\n\n\nExplain what the correct behavior should be under the same conditions.<\/p>\n\n\n\n Example:<\/strong><\/p>\n\n\n\nThe selected template should populate the checklist tab with its content.<\/p>\n\n\n\n 3. Attachments and Environment Context<\/strong><\/p>\n\n\n\nGood bug reports include relevant supporting evidence. Screenshots, Loom videos, or logs help developers see the issue in action, especially when the bug is visual or involves UI interactions. Videos are particularly helpful when the bug is intermittent or hard to describe.<\/p>\n\n\n\n We also include the environment in which the bug occurred – usually Staging, Production, or Development. If it\u2019s not a dedicated Jira field, it should be included at the top of the Description section.<\/p>\n\n\n\n TitanApps tip:<\/strong>
<\/strong> Always indicate the environment and user conditions. Many of our regressions behave differently on Staging vs Production, especially with Forge apps.<\/p>\n\n\n\n4. Neutral, Precise Tone<\/strong><\/p>\n\n\n\nThe tone of a bug report should be factual, not emotional. Avoid phrases like:<\/p>\n\n\n\n |
![\"Check](\"https:\/\/titanapps.io\/blog\/wp-content\/uploads\/2024\/04\/bug-report-1.svg\")
<\/figure>\n\n\n\n![\"\"](\"https:\/\/titanapps.io\/blog\/wp-content\/uploads\/2025\/08\/bug.svg\")
<\/figure>\n\n\n\n