bug-report Reference

Defines the bug classification system, severity guide, and image analysis criteria.

Bug Report Reference Guide#

Defines the bug classification system, severity guide, and image analysis criteria.

1. Severity Classification#

Classification Criteria#

Severity	Label	Icon	Description	Examples
Critical	`severity:critical`	🔴	App unusable, data loss	App crash, ANR, data loss
High	`severity:high`	🟠	Core functionality blocked	Login failure, payment error, main screen inaccessible
Medium	`severity:medium`	🟡	Functionality partially working	Button not working, partial UI broken, data not displayed
Low	`severity:low`	🟢	Minor issues	Typo, alignment error, color error

Severity Decision Flow#

Does the app crash or lose data?
├── Yes → 🔴 Critical
└── No → Is core functionality (login, payment, main flow) blocked?
         ├── Yes → 🟠 High
         └── No → Is the feature not working as intended?
                  ├── Yes → 🟡 Medium
                  └── No → 🟢 Low (visual/surface-level issue)

2. Bug Type Classification#

UI/UX Bugs 🎨#

Sub-type	Description	Examples
Layout	Layout broken	Overflow, overlap, alignment error
Style	Style error	Color, font, margin error
Animation	Animation issue	Jank, non-functional, clipped
Responsive	Responsive issue	Broken at different screen sizes

Functional Bugs ⚙️#

Sub-type	Description	Examples
Navigation	Navigation error	Wrong screen transition, back button error
Input	Input handling error	Keyboard input, touch not recognized
Logic	Logic error	Wrong calculation, condition branching error
State	State management error	State not updated, sync issue

Performance Bugs ⚡#

Sub-type	Description	Examples
Loading	Loading delay	Slow API response, large data
Rendering	Rendering performance	Frame drops, jank
Memory	Memory issue	Memory leak, OOM
Battery	Battery drain	Excessive background work

Crash/ANR 💥#

Sub-type	Description	Examples
Crash	App force close	NPE, unhandled exception
ANR	Not responding	Main thread blocking
Freeze	Screen frozen	Infinite loop, deadlock

Data Bugs 📊#

Sub-type	Description	Examples
Display	Incorrect display	Data not shown, wrong value
Sync	Sync error	Server-client mismatch
Persistence	Storage error	Local save failure, cache error
Validation	Validation error	Invalid input accepted

3. Impact Area Classification#

Area Labels#

Area	Label	Description
UI	`area:ui`	Frontend UI components
Backend	`area:backend`	Server API, endpoints
Data	`area:data`	Data layer, cache
Auth	`area:auth`	Authentication/authorization
Payment	`area:payment`	Payment related
Navigation	`area:navigation`	Routing, navigation

4. Image Analysis Guide#

Analysis Points#

Items to check when analyzing screenshots:

## Image Analysis Checklist

### UI State
- [ ] Is an error dialog displayed?
- [ ] Is it an empty screen (Empty State)?
- [ ] Is the loading state stuck?
- [ ] Is the layout broken?
- [ ] Has an overflow occurred?

### Text Extraction
- [ ] Error message text
- [ ] Screen title/header
- [ ] Button text
- [ ] Input field content

### Context Identification
- [ ] What screen is this? (list, detail, form, etc.)
- [ ] What action preceded this?
- [ ] What data is involved?

Auto-classification Logic#

## Image-based Auto-classification

### Crash/ANR Detection
-  " App is not responding "   → 💥 ANR
-  " Force close "   /  " crash "   → 💥 Crash
- Black screen + error stack → 💥 Crash

### UI Bug Detection
- Text truncated /  " ... "   → 🎨 Layout
- Overlapping elements → 🎨 Layout
- Yellow area (Flutter overflow) → 🎨 Layout

### Functional Bug Detection
- Error toast/snackbar → ⚙️ Function
- Empty list + error icon → ⚙️ Data/Function
- Loading spinner persisting → ⚙️ Function / ⚡ Performance

5. Required Information Collection#

Reproduction Steps Writing Guide#

# Good example
Given the user is logged in
And on the home screen
When tapping the  " Profile "   tab
Then the app crashes

# Bad example
Crash when going to profile

Environment Information Checklist#

## Required Environment Information

| Item | Description | Example |
|------|-------------|---------|
| OS | Operating system version | iOS 17.2, Android 14 |
| Device | Device model | iPhone 15, Galaxy S24 |
| App Version | App version | 1.2.3 (build 456) |
| Account | Test account (optional) | test@example.com |
| Network | Network status (optional) | WiFi, LTE, Offline |

6. Auto-labeling Rules#

Default Labels#

Automatically applied to all bug issues:

bug

Conditional Labels#

Condition	Label
Severity Critical	`severity:critical`, `priority:urgent`
Severity High	`severity:high`, `priority:high`
Crash related	`crash`, `needs-investigation`
UI related	`area:ui`
Reproduction uncertain	`needs-reproduction`

Auto Pipeline#

Severity	Pipeline
Critical	In Progress (immediate handling)
High	Triage (priority classification)
Medium/Low	Backlog

7. Additional Information Formats#

Log Attachment Format#

## Logs

\`\`\`
2024-01-15 10:30:45.123 E/Flutter: Error in authentication flow
2024-01-15 10:30:45.124 E/Flutter: Stack trace:
#0      AuthBloc._onLogin (auth_bloc.dart:45)
#1      Bloc.on. < anonymous closure >   (bloc.dart:123)
\`\`\`

Stack Trace Attachment Format#

## Stack Trace

\`\`\`dart
Exception: Network error
  at ApiClient.fetch (api_client.dart:78)
  at UserRepository.getUser (user_repository.dart:34)
  at GetUserUseCase.call (get_user_usecase.dart:22)
\`\`\`