Bug Handling

Process for reporting and fixing bugs.

Bug Tracking

Platform: GitHub Issues
Labels: bug, severity:critical, severity:major, severity:minor, service:{name}

Severity Levels

Severity	Definition	Response
Critical	Game unplayable, data loss, security vulnerability	Immediate
Major	Feature broken, significant degradation	Within 24 hours
Minor	Cosmetic, minor inconvenience, workaround exists	Next release

Bug Fix Process

1. Triage

Reproduce the bug
Identify affected service(s)
Assign severity level
Determine root cause: spec bug or implementation bug

2. Spec Bug

The specification is incomplete, ambiguous, or incorrect.

Bug Report
    │
    ▼
Spec is wrong/incomplete
    │
    ▼
Update spec in specs/
    │
    ▼
Regenerate service (new version)
    │
    ▼
Run tests (must pass)
    │
    ▼
Deploy new version
    │
    ▼
Close issue

3. Implementation Bug

The code doesn’t match the spec (generation error).

Bug Report
    │
    ▼
Code doesn't match spec
    │
    ▼
Regenerate service from existing spec (new version)
    │
    ▼
Run tests (must pass)
    │
    ▼
Deploy new version
    │
    ▼
Close issue

Service-Level Regeneration

Each service can be regenerated independently:

If bug is in…	Regenerate only…	Other services
physics	physics	Unchanged
players	players	Unchanged
api-gateway	api-gateway	Unchanged
Multiple services	Each affected service	Unchanged

This minimizes:

Blast radius of changes
Testing scope
Deployment risk

Version Numbering for Bug Fixes

Spec bug fix: Increment PATCH (v1.0.0 → v1.0.1)
Implementation regeneration: Increment PATCH
Spec clarification (no behavior change): No version change needed

Issue Template

## Bug Report

**Service**: (e.g., physics, players, web-client)
**Severity**: (critical / major / minor)

### Description
What happened?

### Expected Behavior
What should have happened?

### Steps to Reproduce
1.
2.
3.

### Environment
- Browser (if web-client):
- Game time/tick:
- Ship position (if relevant):

### Logs/Screenshots
(if available)