diff --git a/docs/procedures/gitea-project-management-setup.md b/docs/procedures/gitea-project-management-setup.md new file mode 100644 index 0000000..e780203 --- /dev/null +++ b/docs/procedures/gitea-project-management-setup.md @@ -0,0 +1,496 @@ +# Gitea-Native Project Management — Setup Guide + +**Created:** March 19, 2026 +**Purpose:** Single source of truth for all Firefrost Gaming task management +**Philosophy:** If it's not a Gitea Issue, it doesn't exist + +--- + +## Phase 1: ✅ Global Label Schema (COMPLETE) + +**Status:** All 34 labels created in `firefrost-operations-manual` repository + +### Label Categories Created: + +**STATUS Labels** (Scoped — only one can be applied): +- `status/backlog` — Not yet started, in backlog +- `status/to-do` — Ready to start, in queue +- `status/in-progress` — Currently being worked on +- `status/review` — Work complete, awaiting review +- `status/blocked` — Cannot proceed, blocked by dependency +- `status/done` — Completed and closed + +**PRIORITY Labels** (Scoped): +- `priority/critical` — Emergency, immediate attention +- `priority/high` — Important, address soon +- `priority/medium` — Normal priority +- `priority/low` — Nice to have, not urgent + +**TYPE Labels** (Scoped): +- `type/bug` — Something isn't working +- `type/feature` — New feature or enhancement +- `type/task` — General task or work item +- `type/docs` — Documentation improvements +- `type/infrastructure` — Infrastructure/deployment/DevOps +- `type/refactor` — Code refactoring or technical debt + +**AREA Labels** (Non-scoped — multiple can be applied): +- `area/panel` — Pterodactyl Panel +- `area/wings` — Pterodactyl Wings +- `area/billing` — Paymenter billing system +- `area/email` — Mailcow email system +- `area/website` — Ghost CMS website +- `area/automation` — n8n workflows and automation +- `area/networking` — Network infrastructure +- `area/game-servers` — Minecraft or other game servers +- `area/operations` — General operations and documentation + +**ASSIGNMENT Labels** (Non-scoped): +- `for/holly` — Assigned to Holly (unicorn20089) +- `for/meg` — Assigned to Meg (GingerFury) +- `for/michael` — Assigned to Michael (Frostystyle) + +**SPECIAL Labels** (Non-scoped): +- `help-wanted` — Extra attention needed +- `good-first-issue` — Good for newcomers +- `wont-do` — This will not be worked on + +### To View Labels: + +1. Go to: https://git.firefrostgaming.com/firefrost-gaming/firefrost-operations-manual +2. Click "Labels" in the navigation +3. You'll see all 34 labels with colors and descriptions + +--- + +## Phase 2: Create Organization-Level Project (MANUAL SETUP REQUIRED) + +**Note:** Gitea's Project API is not fully available in v1.21.5, so this must be done via web UI. + +### Step-by-Step: + +**1. Navigate to Organization** +- Go to: https://git.firefrostgaming.com/firefrost-gaming +- Click "Projects" tab at the top + +**2. Create New Project** +- Click "New Project" button (green, top right) +- Fill in details: + - **Title:** `Firefrost Operations` + - **Description:** `Organization-wide task management for Firefrost Gaming infrastructure, operations, and development` + - **Template:** Select "Basic Kanban" + - **Card Previews:** Leave as default or select "Images and Text" + +**3. Click "Create Project"** + +**4. Customize Kanban Columns** + +Default columns may be generic. You can rename/add columns: +- Click on a column name to rename +- Click "New Column" to add more + +**Recommended Columns:** +1. **Backlog** — Tasks not yet ready to start +2. **To Do** — Ready to work on, prioritized +3. **In Progress** — Currently being worked on +4. **Review** — Awaiting review or approval +5. **Done** — Completed tasks + +--- + +## Phase 3: Create Issues and Add to Project + +### Creating an Issue: + +**Method 1: Via Web UI** + +1. Go to any repository (e.g., operations manual) +2. Click "Issues" tab +3. Click "New Issue" +4. Fill in: + - **Title:** Clear, actionable title + - **Description:** Detailed explanation (use Markdown) + - **Labels:** Select appropriate labels (status, priority, type, area) + - **Projects:** Select "Firefrost Operations" + - **Assignees:** Assign to yourself, Holly, or Meg + - **Milestone:** (optional, for grouping related tasks) +5. Click "Create Issue" + +**Method 2: Via Gitea CLI (`tea`)** + +```bash +# Install tea CLI first (if not already installed) +# Linux/Mac: +# Download from: https://gitea.com/gitea/tea/releases + +# Configure tea +tea login add \ + --name firefrost \ + --url https://git.firefrostgaming.com \ + --token e0e330cba1749b01ab505093a160e4423ebbbe36 + +# Create an issue +tea issues create \ + --repo firefrost-gaming/firefrost-operations-manual \ + --title "Deploy ATM10 To The Sky server" \ + --body "Deploy new skyblock server as part of soft launch prep" \ + --labels "type/task,priority/high,area/game-servers,status/to-do,for/michael" +``` + +### Moving Issues on Kanban Board: + +1. Go to: https://git.firefrostgaming.com/org/firefrost-gaming/projects +2. Click on "Firefrost Operations" project +3. You'll see the Kanban board +4. Drag and drop issue cards between columns +5. As you move cards, you can manually update their `status/*` label to match + +--- + +## Phase 4: Issue Templates (YAML) + +Create standardized issue templates to make creating issues faster and more consistent. + +### Step-by-Step: + +**1. Create `.gitea/ISSUE_TEMPLATE/` directory in your repository** + +```bash +cd /firefrost-operations-manual +mkdir -p .gitea/ISSUE_TEMPLATE +``` + +**2. Create Bug Report Template** + +```bash +cat > .gitea/ISSUE_TEMPLATE/bug_report.yaml << 'EOF' +name: Bug Report +about: Report a bug or issue +labels: + - type/bug + - status/to-do +body: + - type: markdown + attributes: + value: | + ## Bug Report + Please provide as much detail as possible. + + - type: input + id: summary + attributes: + label: Summary + description: A brief summary of the bug + placeholder: "e.g., Mailcow cannot send emails" + validations: + required: true + + - type: textarea + id: description + attributes: + label: Description + description: Detailed description of the bug + placeholder: "What happened? What did you expect to happen?" + validations: + required: true + + - type: textarea + id: steps + attributes: + label: Steps to Reproduce + description: How can we reproduce this bug? + placeholder: | + 1. Go to... + 2. Click on... + 3. See error... + validations: + required: true + + - type: dropdown + id: priority + attributes: + label: Priority + options: + - Low + - Medium + - High + - Critical + validations: + required: true + + - type: dropdown + id: area + attributes: + label: Area + options: + - Panel + - Wings + - Billing + - Email + - Website + - Automation + - Networking + - Game Servers + - Operations + validations: + required: true +EOF +``` + +**3. Create Task Template** + +```bash +cat > .gitea/ISSUE_TEMPLATE/task.yaml << 'EOF' +name: Task +about: General task or work item +labels: + - type/task + - status/to-do +body: + - type: markdown + attributes: + value: | + ## Task + Create a new task for the Firefrost Gaming project. + + - type: input + id: title + attributes: + label: Task Title + description: Clear, actionable title + placeholder: "e.g., Deploy ATM10 Sky server" + validations: + required: true + + - type: textarea + id: description + attributes: + label: Description + description: What needs to be done? + placeholder: "Detailed description of the task..." + validations: + required: true + + - type: textarea + id: acceptance + attributes: + label: Acceptance Criteria + description: How do we know this is complete? + placeholder: | + - [ ] Server deployed + - [ ] Tested and verified + - [ ] Documentation updated + + - type: dropdown + id: priority + attributes: + label: Priority + options: + - Low + - Medium + - High + - Critical + default: 1 + validations: + required: true +EOF +``` + +**4. Commit and push templates** + +```bash +git add .gitea/ISSUE_TEMPLATE/ +git commit -m "feat: add issue templates for bug reports and tasks" +git push +``` + +**5. Test the templates** + +1. Go to repository Issues page +2. Click "New Issue" +3. You should now see template options: "Bug Report" and "Task" +4. Select one to create a pre-formatted issue + +--- + +## Phase 5: n8n Automation (Future) + +**Purpose:** Automate notifications and maintenance tasks + +### Planned Automations: + +**1. Discord Notifications** +- New issue created → Discord #dev-notifications +- Issue assigned to you → Discord DM +- Issue status changed → Discord update + +**2. Auto-Labeling** +- Issue mentions "bug" → auto-apply `type/bug` +- Issue mentions "urgent" → auto-apply `priority/high` +- Issue mentions specific system → auto-apply `area/*` + +**3. Status Reports** +- Weekly summary of open issues +- Monthly progress report +- Burndown tracking + +**Implementation:** +- n8n workflow listening to Gitea webhooks +- Parse issue events +- Route to Discord, apply labels, etc. + +--- + +## Workflow Examples + +### Example 1: Holly Gets a Task + +**Michael creates task:** +1. Go to Issues → New Issue +2. Use "Task" template +3. Title: "Backup 10 retiring servers" +4. Description: (paste from checklist) +5. Labels: `type/task`, `priority/high`, `area/game-servers`, `for/holly` +6. Projects: "Firefrost Operations" +7. Assignees: Holly +8. Create Issue + +**Holly works on it:** +1. Goes to Firefrost Operations Kanban +2. Sees issue in "To Do" column +3. Drags to "In Progress" +4. Updates `status/in-progress` label +5. Does the work +6. Comments on issue with progress +7. When done, drags to "Done" +8. Updates `status/done` label +9. Closes issue + +### Example 2: Bug Report + +**Meg finds a bug:** +1. Issues → New Issue → "Bug Report" template +2. Fills in form (summary, description, steps, priority, area) +3. Creates issue +4. Michael sees it in Kanban "To Do" column +5. Assigns to himself +6. Moves to "In Progress" +7. Fixes bug +8. Commits with reference: `git commit -m "fix: mailcow SMTP issue (closes #123)"` +9. Issue auto-closes when commit is pushed + +### Example 3: Feature Request + +**Michael plans new feature:** +1. Creates issue with `type/feature` label +2. Assigns `status/backlog` (not ready yet) +3. Adds to Kanban "Backlog" column +4. When ready to start, moves to "To Do" +5. Changes status to `status/to-do` +6. Begins work, moves to "In Progress" +7. Finishes, moves to "Review" +8. Holly reviews, approves +9. Moves to "Done", closes issue + +--- + +## Migration from tasks.md + +**Current:** `docs/core/tasks.md` has a big list of tasks + +**New Approach:** +1. Convert each task to a Gitea Issue +2. Apply appropriate labels +3. Add to "Firefrost Operations" project +4. Archive old tasks.md (keep for reference) + +**Migration Script Concept:** + +```bash +# Parse tasks.md +# For each task: +# - Create Gitea issue via API +# - Apply labels based on task content +# - Add to project + +# Example for one task: +tea issues create \ + --repo firefrost-gaming/firefrost-operations-manual \ + --title "Task #48: Gitea/Plane Integration" \ + --body "Status: WON'T DO - Plane not needed, Gitea has native Kanban" \ + --labels "type/task,status/done,wont-do,area/automation" +``` + +--- + +## Benefits of This Approach + +✅ **Single Source of Truth** +- All tasks in one place (Gitea) +- No sync complexity +- No Plane middleware + +✅ **Visual Management** +- Kanban board for progress tracking +- Drag-and-drop simplicity +- Color-coded labels + +✅ **Organization-Wide** +- One board across all repos +- Issues from any repo show up +- Unified view of all work + +✅ **Standardization** +- Consistent labels across projects +- Issue templates enforce structure +- Less manual typing (accessibility win!) + +✅ **Git Integration** +- Link commits to issues +- Auto-close issues with commit messages +- Full audit trail + +✅ **Automation Ready** +- Gitea webhooks available +- n8n can listen and act +- Discord notifications + +✅ **No External Dependencies** +- Self-hosted +- No third-party services +- Data sovereignty + +--- + +## Next Actions + +**Immediate (Manual Setup):** +1. [ ] Create "Firefrost Operations" organization project via web UI +2. [ ] Set up Kanban columns (Backlog, To Do, In Progress, Review, Done) +3. [ ] Create a test issue and add it to the project +4. [ ] Verify labels are working +5. [ ] Create issue templates in operations manual repo + +**Short Term:** +1. [ ] Migrate existing tasks from tasks.md to Gitea Issues +2. [ ] Document workflow for Holly and Meg +3. [ ] Train team on using Kanban board + +**Long Term:** +1. [ ] Set up n8n webhooks for Discord notifications +2. [ ] Build auto-labeling automation +3. [ ] Create weekly status report automation +4. [ ] Explore Gitea Actions for CI/CD integration + +--- + +## Resources + +- **Gitea Documentation:** https://docs.gitea.com +- **Gitea Projects Guide:** https://blog.gitea.com/introducing-new-features-of-labels-and-projects/ +- **Operations Manual:** `git.firefrostgaming.com/firefrost-gaming/firefrost-operations-manual` +- **Your Gitea Instance:** https://git.firefrostgaming.com + +--- + +**Fire + Frost + Foundation = Where Love Builds Legacy** 💙🔥❄️