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/holly': 27,
|
||||||
'for/meg': 28,
|
'for/meg': 28,
|
||||||
'for/michael': 29,
|
'for/michael': 29,
|
||||||
|
'needs-board-sync': 34,
|
||||||
'priority/critical': 8,
|
'priority/critical': 8,
|
||||||
'priority/high': 9,
|
'priority/high': 9,
|
||||||
'priority/low': 11,
|
'priority/low': 11,
|
||||||
@@ -172,6 +173,11 @@ class Task:
|
|||||||
def get_label_ids(self) -> List[int]:
|
def get_label_ids(self) -> List[int]:
|
||||||
"""Get all label IDs for this task"""
|
"""Get all label IDs for this task"""
|
||||||
label_names = [self.status, self.priority, self.task_type] + self.assignees + self.areas
|
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]
|
return [LABEL_IDS[name] for name in label_names if name in LABEL_IDS]
|
||||||
|
|
||||||
def to_issue_body(self) -> str:
|
def to_issue_body(self) -> str:
|
||||||
|
|||||||
Reference in New Issue
Block a user