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:
128
docs/reference/project-board-sync-workflow.md
Normal file
128
docs/reference/project-board-sync-workflow.md
Normal 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
|
||||
@@ -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:
|
||||
|
||||
Reference in New Issue
Block a user