feat: implement needs-board-sync label workflow

IMPLEMENTED: Label-based project board sync workflow

Changes:
- Created needs-board-sync label (ID: 34, orange #FFA500)
- Modified sync script to auto-add label to new non-complete issues
- Created manual workflow documentation

Why this approach:
- Gitea Projects REST API does NOT exist even in 1.25.5
- Gemini was incorrect about API availability in 1.22+
- Projects API still in development (PR #36824, targeting 1.26.0+)
- Confirmed via swagger spec: zero /projects endpoints exist

How it works:
1. Sync script creates issues with needs-board-sync label
2. Filter by label in Gitea UI
3. Drag to project board (Backlog column)
4. Remove label after syncing
5. Takes 30-60 seconds per sync session

Future automation:
When Gitea 1.26.0+ releases with Projects API, we'll modify
the sync script to use /projects/ endpoints and remove this
manual workflow.

Related: Gitea successfully upgraded to 1.25.5 earlier this session

Signed-off-by: The Chronicler <claude@firefrostgaming.com>
This commit is contained in:
Claude
2026-03-21 08:09:37 +00:00
parent 000eaa8c7f
commit fa5ca37330
2 changed files with 134 additions and 0 deletions

View File

@@ -0,0 +1,128 @@
# Manual Workflow: Syncing New Issues to Project Board
**Created:** March 21, 2026
**Status:** ACTIVE (until Gitea Projects API becomes available)
**Estimated Time:** 30-60 seconds per sync session
---
## Why This Workflow Exists
**The Problem:**
- Gitea's Projects REST API doesn't exist yet (not even in 1.25.5)
- Gemini was incorrect about API availability in 1.22+
- Projects API is in development (PR #36824, targeting 1.26.0+)
**The Solution:**
- Automated sync script adds `needs-board-sync` label to new issues
- Manual step: drag labeled issues to project board
- Remove label after adding to board
---
## The Workflow
### Step 1: Run Task Sync Script
Whenever you add tasks to `docs/core/tasks.md`:
```bash
cd /home/claude/firefrost-operations-manual
python3 scripts/sync-tasks-to-issues.py
```
**What happens:**
- Script creates Gitea issues for new tasks
- Automatically adds `needs-board-sync` label (orange) to non-complete tasks
- Issues with `status/done` do NOT get the sync label
### Step 2: Filter Issues in Gitea
1. Open https://git.firefrostgaming.com/firefrost-gaming/firefrost-operations-manual/issues
2. Click "Labels" dropdown
3. Select `needs-board-sync` (orange label)
4. You'll see all issues that need to be added to the project board
### Step 3: Add to Project Board
1. Open the Firefrost Operations project board:
https://git.firefrostgaming.com/orgs/firefrost-gaming/projects/1
2. For each issue with `needs-board-sync` label:
- Drag the issue card to the appropriate column:
- **Backlog** - Default for most new tasks
- **Michael - Tasks** - If assigned to Michael
- **Meg - Tasks** - If assigned to Meg
- **Holly - Tasks** - If assigned to Holly
- Or click the issue → "Projects" dropdown → Select "Firefrost Operations" → Choose column
### Step 4: Remove Label
After adding to board:
1. Open the issue
2. Click the `needs-board-sync` label to remove it
3. Issue is now synced!
**Pro tip:** You can bulk-remove labels:
- Select multiple issues (checkboxes on left)
- Actions dropdown → "Remove label" → `needs-board-sync`
---
## Quick Reference
**Label created:** March 21, 2026
**Label ID:** 34
**Label color:** #FFA500 (orange)
**Description:** "New issue needs to be added to project board"
**Filter URL:**
https://git.firefrostgaming.com/firefrost-gaming/firefrost-operations-manual/issues?labels=34
**Project Board:**
https://git.firefrostgaming.com/orgs/firefrost-gaming/projects/1
---
## When This Workflow Will Become Automated
**Current Gitea version:** 1.25.5
**Projects API availability:** Not yet (in development)
**Target version:** 1.26.0+ (estimated)
**When 1.26.0+ is released:**
1. Upgrade Gitea to version with Projects API
2. Modify sync script to use `/projects/` endpoints
3. Auto-add new issues to "Backlog" column via API
4. Remove `needs-board-sync` label logic
5. Archive this manual workflow document
---
## Troubleshooting
**Q: Why don't I see the `needs-board-sync` label on some new issues?**
A: Issues marked as `✅ COMPLETE` in tasks.md don't get the label (they're already done, no need to add to board)
**Q: Can I filter by multiple labels?**
A: Yes! Click multiple labels to see issues with ALL selected labels
**Q: What if I forget to remove the label?**
A: No problem - the label is just a reminder. It doesn't affect anything if you leave it on.
**Q: Can I change the label color?**
A: Yes! Go to Repository → Labels → Edit the `needs-board-sync` label
---
## Related Documentation
- `scripts/sync-tasks-to-issues.py` - Automated sync script
- `docs/tasks/gitea-upgrade/` - Gitea 1.25.5 upgrade documentation
- `docs/reference/cockpit-quick-reference.md` - Server access guide
---
**Created by:** The Chronicler (Session 37)
**Last Updated:** March 21, 2026
**Status:** ACTIVE - Manual workflow until Projects API available

View File

@@ -41,6 +41,7 @@ LABEL_IDS = {
'for/holly': 27,
'for/meg': 28,
'for/michael': 29,
'needs-board-sync': 34,
'priority/critical': 8,
'priority/high': 9,
'priority/low': 11,
@@ -172,6 +173,11 @@ class Task:
def get_label_ids(self) -> List[int]:
"""Get all label IDs for this task"""
label_names = [self.status, self.priority, self.task_type] + self.assignees + self.areas
# Add needs-board-sync label UNLESS task is already complete
if self.status != 'status/done':
label_names.append('needs-board-sync')
return [LABEL_IDS[name] for name in label_names if name in LABEL_IDS]
def to_issue_body(self) -> str: