diff --git a/docs/reference/project-board-sync-workflow.md b/docs/reference/project-board-sync-workflow.md new file mode 100644 index 0000000..7e52ccd --- /dev/null +++ b/docs/reference/project-board-sync-workflow.md @@ -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 diff --git a/scripts/sync-tasks-to-issues.py b/scripts/sync-tasks-to-issues.py index 8bc72e7..dcdf215 100755 --- a/scripts/sync-tasks-to-issues.py +++ b/scripts/sync-tasks-to-issues.py @@ -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: