firefrost-gaming/firefrost-operations-manual
3
0
Fork 0
Code Issues 146 Pull Requests Packages Projects Releases Wiki Activity

docs: create comprehensive Gitea-native project management setup guide

Browse Source 
PHASE 1 COMPLETE: Global Label Schema
- Created 34 standardized labels via Gitea API
- 6 status labels (scoped)
- 4 priority labels (scoped)
- 6 type labels (scoped)
- 9 area labels (non-scoped)
- 3 assignment labels (for Holly/Meg/Michael)
- 3 special labels

Labels successfully applied to operations manual repository.

PHASE 2-5 DOCUMENTED:
- Organization-level project creation (manual via web UI)
- Issue creation workflow (web UI + tea CLI)
- Issue templates (YAML examples for bug reports and tasks)
- n8n automation plans (Discord notifications, auto-labeling)

COMPLETE SETUP GUIDE:
- Step-by-step instructions for creating Kanban project
- Workflow examples (Holly gets task, bug report, feature request)
- Migration plan from tasks.md to Gitea Issues
- Benefits of Gitea-native approach vs Plane.io

DECOMMISSIONED:
- Plane.io integration (Task #48 = WON'T DO)
- No external sync needed
- Single source of truth = Gitea

Related to Gemini's architectural brief and shift to stateless
Gitea-native lifecycle management.

Next: Michael to create org project via web UI, then we migrate
tasks from tasks.md to Gitea Issues.
This commit is contained in:
Claude
2026-03-19 19:11:55 +00:00
parent 023fa558a3
commit ca44aef925
1 changed files with 496 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

496
docs/procedures/gitea-project-management-setup.md Normal file
View File

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