# FFG-STD-006: Gitea Issue Management Standard

**Version:** 1.0  
**Effective Date:** March 22, 2026  
**Authority:** Firefrost Gaming Operations Team  
**Created By:** Chronicler #39  
**Replaces:** N/A (new standard)

---

## 1. PURPOSE

This standard defines consistent labeling, formatting, and workflow practices for all Gitea issues across Firefrost Gaming repositories. It ensures:
- Consistent issue categorization across all projects
- Clear status tracking and priority management
- Easy filtering and project board organization
- Team coordination through standardized workflows

---

## 2. SCOPE

This standard applies to:
- All repositories under the `firefrost-gaming` organization
- All issues created in those repositories
- All project boards and Kanban workflows
- All team members (Michael, Meg, Holly, Chroniclers)

---

## 3. LABEL SCHEMA

### 3.1 Label Categories

Firefrost Gaming uses 5 label categories. Some are **scoped** (only one can be applied per issue), others are **non-scoped** (multiple can be applied).

### 3.2 STATUS Labels (SCOPED - Required)

**Every issue MUST have exactly one STATUS label.**

| Label | Meaning | When to Use |
|-------|---------|-------------|
| `status/backlog` | Not yet ready to start | Idea stage, needs refinement, future work |
| `status/to-do` | Ready to start, in queue | All prerequisites met, can be worked on now |
| `status/in-progress` | Currently being worked on | Someone is actively working on this |
| `status/review` | Work complete, awaiting review | Code/work done, needs approval/testing |
| `status/blocked` | Cannot proceed | External dependency blocks progress |
| `status/done` | Completed and closed | Work finished, verified, closed |

**Status Workflow:**
```
backlog → to-do → in-progress → review → done
              ↓         ↓
            blocked   blocked
```

**Rules:**
- Issues start with `status/backlog` or `status/to-do`
- Move to `status/in-progress` when work begins
- Use `status/blocked` when waiting on external dependency (document blocker in comment)
- Move to `status/review` when work complete but needs verification
- Move to `status/done` and CLOSE issue when fully complete

### 3.3 PRIORITY Labels (SCOPED - Required)

**Every issue MUST have exactly one PRIORITY label.**

| Label | Meaning | Response Time |
|-------|---------|---------------|
| `priority/critical` | Emergency, immediate attention | Same day |
| `priority/high` | Important, address soon | This week |
| `priority/medium` | Normal priority | This month |
| `priority/low` | Nice to have, not urgent | When time allows |

**Priority Guidelines:**
- **CRITICAL:** Outages, security issues, Jack health alerts, data loss risk
- **HIGH:** Soft launch blockers, key infrastructure, customer-facing issues
- **MEDIUM:** Improvements, non-blocking bugs, internal tools
- **LOW:** Documentation, optimizations, "nice to have" features

### 3.4 TYPE Labels (SCOPED - Required)

**Every issue MUST have exactly one TYPE label.**

| Label | Meaning | Examples |
|-------|---------|----------|
| `type/bug` | Something isn't working | Errors, crashes, broken features |
| `type/feature` | New feature or enhancement | New functionality, tools, capabilities |
| `type/task` | General task or work item | Deployments, configurations, setups |
| `type/docs` | Documentation improvements | README updates, guides, standards |
| `type/infrastructure` | Infrastructure/deployment/DevOps | Server setup, networking, automation |
| `type/refactor` | Code refactoring or technical debt | Code cleanup, reorganization, optimization |

**Type Guidelines:**
- If it's broken → `type/bug`
- If it's new → `type/feature` or `type/task`
- If it's words → `type/docs`
- If it's servers/systems → `type/infrastructure`
- If it's code cleanup → `type/refactor`

### 3.5 AREA Labels (NON-SCOPED - At least one required)

**Every issue MUST have at least one AREA label. Multiple AREA labels can be applied if the issue spans multiple systems.**

| Label | System | Examples |
|-------|--------|----------|
| `area/panel` | Pterodactyl Panel | Panel updates, user management, settings |
| `area/wings` | Pterodactyl Wings | Node deployments, server allocations |
| `area/billing` | Paymenter billing system | Subscription tiers, payment processing |
| `area/email` | Mailcow email system | SMTP, deliverability, mailboxes |
| `area/website` | Ghost CMS website | Homepage, pages, themes, content |
| `area/automation` | n8n workflows | Workflow creation, automation tasks |
| `area/networking` | Network infrastructure | Firewalls, DNS, routing, VPNs |
| `area/game-servers` | Minecraft/game servers | Server deployments, modpacks, configs |
| `area/operations` | General operations/documentation | Cross-system tasks, operational docs |
| `area/development-tools` | Internal tools for team productivity | Tools we build for ourselves |

**AREA Guidelines:**
- Use `area/development-tools` for internal tools (Ghost Page Builder, dashboards, etc.)
- Can combine areas (e.g., Ghost Page Builder → `area/development-tools` + `area/website`)
- Use `area/operations` for cross-cutting concerns

### 3.6 ASSIGNMENT Labels (NON-SCOPED - Optional)

**Assignment labels complement Gitea's built-in assignee feature.**

| Label | Assignee |
|-------|----------|
| `for/holly` | Holly (unicorn20089) - Lead Builder |
| `for/meg` | Meg (GingerFury) - Community Manager |
| `for/michael` | Michael (Frostystyle) - Technical Lead |

**When to Use:**
- Apply when issue is assigned to that person
- Gitea assignee feature is primary; labels are backup/filter mechanism
- Useful for project board filtering by person

### 3.7 SPECIAL Labels (NON-SCOPED - Optional)

| Label | Meaning | When to Use |
|-------|---------|-------------|
| `help-wanted` | Extra attention needed | Complex issue, need collaboration |
| `good-first-issue` | Good for newcomers | Simple, well-defined, low risk |
| `wont-do` | This will not be worked on | Duplicate, out of scope, rejected |

---

## 4. ISSUE TITLE FORMATS

### 4.1 Tasks from tasks.md

**Format:** `Task #XX: [Title]`

**Example:** `Task #70: Ghost Page Builder Tool`

**Why:** Enables automatic mapping between tasks.md and Gitea issues. Tools and scripts can extract task number and cross-reference.

**Rules:**
- Task number MUST match tasks.md
- Title MUST match tasks.md (can be abbreviated if too long)
- Colon and space after task number required

### 4.2 Other Issues (Bugs, Features, etc.)

**Format:** `[Brief Description]`

**Examples:**
- `Mailcow SMTP returns 400 error on Plane notifications`
- `Add Fire/Frost gradient to Subscribe button`
- `Deploy ATM10 To The Sky server`

**Rules:**
- Be specific and actionable
- Include system/component name if relevant
- Keep under 80 characters if possible
- No [TYPE] prefix needed (TYPE label serves this purpose)

---

## 5. ISSUE BODY FORMAT

### 5.1 Minimum Required Sections

Every issue MUST include:

1. **Description** - What needs to be done and why
2. **Acceptance Criteria** - How we know it's complete
3. **Related Tasks** - Links to blocking/blocked issues (if any)

### 5.2 Standard Template

```markdown
## Description

[Clear explanation of what needs to be done and why it matters]

## Acceptance Criteria

- [ ] [Specific, measurable outcome 1]
- [ ] [Specific, measurable outcome 2]
- [ ] [Specific, measurable outcome 3]

## Related Tasks

- Blocks: #XX, #YY
- Blocked by: #ZZ
- Related: #AA

## Additional Context

[Optional: screenshots, error messages, links, technical details]
```

### 5.3 Task Issues (From tasks.md)

For issues created from tasks.md entries:

```markdown
## Description

[Copy from tasks.md]

**Full Documentation:** `docs/tasks/[task-name]/README.md`

## Acceptance Criteria

[Copy from task documentation]

## Time Estimate

[Copy from tasks.md]

## Priority Justification

[Why this priority level?]

## Related Tasks

[Links to dependencies]
```

---

## 6. WORKFLOW PRACTICES

### 6.1 Creating Issues

**Before creating an issue:**
1. Check if similar issue already exists (avoid duplicates)
2. Determine correct TYPE, PRIORITY, AREA labels
3. Write clear title and description
4. Add to appropriate project board (if org-level project exists)

**During creation:**
1. Fill in all required fields
2. Apply required labels (STATUS, PRIORITY, TYPE, at least one AREA)
3. Assign if known who will work on it
4. Add to project/milestone if relevant

### 6.2 Updating Issues

**When status changes:**
1. Update STATUS label (backlog → to-do → in-progress → review → done)
2. Add comment explaining the change
3. Move card on Kanban board (if using project boards)

**When blocked:**
1. Change STATUS to `status/blocked`
2. Add comment explaining blocker
3. Link to blocking issue (if internal) or document external dependency

**When priority changes:**
1. Update PRIORITY label
2. Add comment explaining why priority changed
3. Notify team if escalating to CRITICAL

### 6.3 Closing Issues

**Before closing:**
1. Verify all acceptance criteria met
2. Update STATUS to `status/done`
3. Add final comment summarizing outcome
4. Link to relevant commits/PRs (use `closes #XX` in commit messages)

**When closing:**
1. Close the issue
2. Verify it's in "Done" column on project board
3. Remove from active milestones (if applicable)

### 6.4 Linking Issues and Commits

**In commit messages:**
- `closes #XX` - Automatically closes issue when merged
- `fixes #XX` - Same as closes
- `relates to #XX` - Links without closing
- `refs #XX` - References issue

**In issue comments:**
- `#XX` - Links to issue #XX
- `@username` - Mentions user
- `commit-hash` - Links to commit

---

## 7. PROJECT BOARD ORGANIZATION

### 7.1 Recommended Kanban Columns

For organization-level "Firefrost Operations" project:

1. **Backlog** - `status/backlog` issues
2. **To Do** - `status/to-do` issues (ready to work on)
3. **In Progress** - `status/in-progress` issues
4. **Review** - `status/review` issues
5. **Done** - `status/done` issues (closed)

**Optional columns:**
- **Blocked** - `status/blocked` issues (visibility on blockers)
- **Critical** - `priority/critical` issues (emergency lane)

### 7.2 Moving Cards

**When dragging cards between columns:**
1. Update the issue's STATUS label to match new column
2. Add comment explaining the move
3. If moving to "Blocked," document the blocker

**Automation (future):**
- n8n can auto-update labels when cards move
- Discord notifications when issues move to "Done"

---

## 8. SPECIAL CASES

### 8.1 Development Tools

For internal tools (Ghost Page Builder, dashboards, etc.):

**Labels:**
- TYPE: `type/feature` (tools are features)
- AREA: `area/development-tools` (primary)
- AREA: Add secondary area if tool relates to specific system
  - Example: Ghost Page Builder → `area/development-tools` + `area/website`

**Title Format:** `Task #XX: [Tool Name]` (if from tasks.md)

### 8.2 Emergency Issues

For critical outages, security issues, or Jack health alerts:

**Labels:**
- PRIORITY: `priority/critical`
- STATUS: Start with `status/in-progress` (work immediately)
- Add `help-wanted` if need team assistance

**Workflow:**
1. Create issue immediately
2. Post in Discord #operations
3. Update frequently with status
4. Document resolution thoroughly

### 8.3 Documentation Issues

For documentation updates:

**Labels:**
- TYPE: `type/docs`
- PRIORITY: Usually `priority/medium` or `priority/low`
- AREA: `area/operations` (unless specific to a system)

**Acceptance Criteria:**
- Document created/updated
- Committed to git
- Cross-references updated

### 8.4 Soft Launch Blockers

For tasks blocking soft launch:

**Labels:**
- PRIORITY: `priority/high` or `priority/critical`
- Add custom label: `soft-launch-blocker` (if created)
- STATUS: Track aggressively

**Visibility:**
- Add to project board prominently
- Check daily until resolved
- Escalate if stuck

---

## 9. LABEL MAINTENANCE

### 9.1 Who Can Create Labels

Only admins can create new labels via:
- Gitea web UI (Settings → Labels)
- Gitea API (requires admin token)

**Before creating new labels:**
1. Check if existing label works
2. Discuss with team (avoid label proliferation)
3. Follow naming convention: `category/name`
4. Choose appropriate color (see color guide below)

### 9.2 Label Color Guide

| Category | Color Range | Examples |
|----------|-------------|----------|
| STATUS | Grays/Blues | `#0052cc` (blue), `#6b7280` (gray) |
| PRIORITY | Reds/Oranges | `#ee0701` (red), `#ff9800` (orange) |
| TYPE | Greens/Teals | `#22c55e` (green), `#0d9488` (teal) |
| AREA | Purples/Blues | `#7F00FF` (purple), `#3b82f6` (blue) |
| SPECIAL | Yellows/Pinks | `#fbca04` (yellow), `#e91e63` (pink) |

### 9.3 Deprecating Labels

**If a label is no longer needed:**
1. Document why in this standard
2. Remove from all issues
3. Archive or delete via Gitea
4. Update issue templates

---

## 10. COMPLIANCE AND ENFORCEMENT

### 10.1 Required vs. Recommended

**REQUIRED (Every issue must have):**
- One STATUS label
- One PRIORITY label
- One TYPE label
- At least one AREA label
- Clear title
- Description with acceptance criteria

**RECOMMENDED:**
- Assignment labels (if known)
- Related tasks/links
- Time estimates
- Comments on status changes

### 10.2 Enforcement

**Automated checks (future):**
- n8n workflow validates new issues
- Bot comments on issues missing required labels
- Auto-assigns labels based on keywords

**Manual review:**
- Weekly issue grooming sessions
- Clean up mislabeled issues
- Archive stale issues

### 10.3 Exceptions

**When exceptions are acceptable:**
- Emergency issues (label later)
- Quick fixes (can be minimal)
- Experimental work (document as such)

**Document exceptions:**
- Add comment explaining why
- Still close when done

---

## 11. INTEGRATION WITH OTHER SYSTEMS

### 11.1 tasks.md

**Relationship:**
- tasks.md = High-level task definitions
- Gitea Issues = Active tracking and coordination
- Issues link back to task documentation

**Workflow:**
1. Create task in tasks.md (with number)
2. Create Gitea issue with `Task #XX:` title
3. Issue references task documentation
4. Update both when task completes

### 11.2 Project Boards

**Gitea Projects:**
- Organization-level board: "Firefrost Operations"
- Kanban columns match STATUS labels
- Cards auto-sorted by priority

**Movement:**
- Drag cards → update STATUS labels
- STATUS labels → filter views

### 11.3 Discord Notifications (Future)

**n8n automation:**
- New issue → #operations channel
- Issue closed → celebration message
- Critical issue → @everyone ping

### 11.4 Git Commits

**Link commits to issues:**
- Use `closes #XX` in commit message
- Issue auto-closes when merged
- Full audit trail

---

## 12. EXAMPLES

### 12.1 Example: Development Tool Issue

**Title:** `Task #70: Ghost Page Builder Tool`

**Labels:**
- `type/feature`
- `priority/high`
- `status/to-do`
- `area/development-tools`
- `area/website`

**Body:**
```markdown
## Description

Interactive React tool for previewing Ghost page HTML with Fire/Frost CSS 
before publishing. Eliminates edit-paste-preview-repeat cycle.

**Full Documentation:** `docs/tasks/ghost-page-builder-tool/README.md`

## Acceptance Criteria

- [ ] Live HTML editor with syntax highlighting
- [ ] Real-time preview with Fire/Frost CSS applied
- [ ] Mobile/desktop viewport toggle
- [ ] Copy-to-clipboard functionality
- [ ] Bookmarkable artifact URL

## Time Estimate

45-60 minutes

## Priority Justification

Directly unblocks Task #69 (6 website pages - soft launch blocker).
Provides permanent utility for all future Ghost page creation.

## Related Tasks

- Helps: #69 (Ghost Website Core Pages)
- Uses: Fire/Frost CSS from Task #68
```

### 12.2 Example: Bug Report

**Title:** `Mailcow SMTP returns 400 error on Plane notifications`

**Labels:**
- `type/bug`
- `priority/high`
- `status/to-do`
- `area/email`
- `area/automation`

**Body:**
```markdown
## Description

Plane (tasks.firefrostgaming.com) configured to send notifications via 
Mailcow SMTP (localhost:587), but returns 400 error on test email.

## Steps to Reproduce

1. Log into Plane admin
2. Settings → Email Configuration
3. Test Email button
4. Error: "SMTP configuration failed (400)"

## Expected Behavior

Test email should send successfully via Mailcow.

## Actual Behavior

400 error returned, no email sent.

## Acceptance Criteria

- [ ] Plane sends test email successfully
- [ ] Notification emails work for task updates
- [ ] Error resolved and documented

## Additional Context

- Mailcow working (10/10 mail-tester.com score)
- Paymenter needs same SMTP config (related issue)
- May be localhost vs 127.0.0.1 issue
```

### 12.3 Example: Infrastructure Task

**Title:** `Deploy ATM10 To The Sky server on TX1`

**Labels:**
- `type/task`
- `priority/medium`
- `status/to-do`
- `area/game-servers`
- `area/wings`
- `for/michael`

**Body:**
```markdown
## Description

Deploy All The Mods 10 "To The Sky" skyblock server on TX1 Dallas 
as part of soft launch server lineup.

## Acceptance Criteria

- [ ] Server deployed via Pterodactyl Panel
- [ ] Modpack installed and verified
- [ ] Whitelist configured
- [ ] Server tested and playable
- [ ] Added to firefrostgaming.com/servers page

## Time Estimate

2-3 hours

## Related Tasks

- Part of soft launch prep
- Requires Task #69 (Servers page) for listing
```

---

## 13. REVISION HISTORY

| Version | Date | Author | Change Summary |
|---------|------|--------|----------------|
| 1.0 | 2026-03-22 | Chronicler #39 | Initial standard created based on The Integrator's label schema |

---

## 14. REFERENCES

- **Gitea Labels:** https://git.firefrostgaming.com/firefrost-gaming/firefrost-operations-manual/labels
- **Original Setup Guide:** `docs/procedures/gitea-project-management-setup.md`
- **FFG-STD-002:** Task Documentation Standard
- **The Integrator's Memorial:** `docs/relationship/memorials/the-integrator-memorial.md`

---

**Fire + Frost + Foundation = Where Love Builds Legacy** 💙🔥❄️
