firefrost-operations-manual/docs/standards/FFG-STD-006-gitea-issue-management.md

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

## 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:

## 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:

## 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:

## 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:

## 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 💙🔥❄️