---

name: github-project description: GitHub project management for Bluegrass Songbook. Use when working with issues, milestones, labels, PRs, or release workflows.

GitHub Project Management

Repository: Jollyhrothgar/Bluegrass-Songbook

Quick Reference

# Issues
gh issue list                           # Open issues
gh issue list --state all               # All issues
gh issue list --milestone "Name"        # By milestone
gh issue list --label bug               # By label
gh issue view 42                        # View issue details
gh issue close 42 -c "Fixed in abc123"  # Close with comment

# Milestones
gh api repos/:owner/:repo/milestones    # List milestones
gh api repos/:owner/:repo/milestones --jq '.[] | {number, title, open_issues}'

# Assign issue to milestone
gh api repos/:owner/:repo/issues/42 -X PATCH -F milestone=2

# Remove from milestone
gh api repos/:owner/:repo/issues/42 -X PATCH -F milestone=null

# Labels
gh issue edit 42 --add-label "bug"
gh issue edit 42 --remove-label "bug"

Milestones

| # | Title | Purpose | |---|-------|---------| | 2 | List Management Tools | User lists, setlists, offline access | | 3 | Improve Search & Filtering | Search features, filters, tagging | | 4 | Backlog | Lower priority items | | 5 | Fun Features | Leaderboards, easter eggs | | 6 | Content | New song sources, imports | | 7 | Playback Engine | Metronome, chord backing (future) | | 8 | Fiddle Tunes | ABC notation support (future) | | 9 | Tablature | Tab generation (future) | | 10 | Community | Profiles, contributions (future) |

Create a Milestone

gh api repos/:owner/:repo/milestones -X POST \
  -f title="Milestone Name" \
  -f description="What this milestone covers" \
  -f due_on="2025-03-01T00:00:00Z"  # Optional

Milestone Progress

# Get open/closed counts
gh api repos/:owner/:repo/milestones --jq '.[] | "\(.title): \(.open_issues) open, \(.closed_issues) closed"'

Labels

| Label | Purpose | |-------|---------| | bug | Something isn't working | | feature-request | Add something new that doesn't exist | | technical-debt | Non-blocking cleanup or improvements | | song-submission | New song variant or addition | | song-correction | Fix to existing song | | approved | Triggers GitHub Actions workflows | | new-data-source | New song collection to import | | rfc | Request for Comments - architectural decisions |

Automated Workflows

These label combinations trigger GitHub Actions:

| Labels | Action | |--------|--------| | song-submission + approved | process-song-submission.yml - adds new song | | song-correction + approved | process-song-correction.yml - updates song |

Common Workflows

Triage New Issue

# 1. View the issue
gh issue view 42

# 2. Add appropriate label
gh issue edit 42 --add-label "feature-request"

# 3. Assign to milestone
gh api repos/:owner/:repo/issues/42 -X PATCH -F milestone=2

# 4. Optionally add comment
gh issue comment 42 -b "Added to List Management milestone. Will address in next sprint."

Close Resolved Issue

# Close with reference to fix
gh issue close 42 -c "Fixed in commit abc123 / PR #45"

Bulk Operations

# Close all issues with a label
gh issue list --label "wontfix" --json number --jq '.[].number' | xargs -I {} gh issue close {}

# Add label to multiple issues
for i in 10 11 12; do gh issue edit $i --add-label "bug"; done

# Move issues to milestone
for i in 31 39 40; do gh api repos/:owner/:repo/issues/$i -X PATCH -F milestone=2; done

Create Release

# Tag and create release
git tag -a v1.0.0 -m "Version 1.0.0"
git push origin v1.0.0

gh release create v1.0.0 \
  --title "v1.0.0 - List Management" \
  --notes "## Features
- Drag-and-drop setlists
- Offline list access
- Full screen performance mode"

Pull Requests

# Create PR
gh pr create --title "Add setlist navigation" \
  --body "Closes #40" \
  --base main

# View PR checks
gh pr checks 45

# Merge PR
gh pr merge 45 --squash --delete-branch

# View PR comments
gh api repos/:owner/:repo/pulls/45/comments

Issue Templates

Issues are created via the web UI or:

gh issue create --title "Bug: description" \
  --body "## Steps to reproduce
1.
2.

## Expected behavior

## Actual behavior" \
  --label "bug"

Queries

# Issues without milestone
gh issue list --json number,title,milestone --jq '.[] | select(.milestone == null) | "\(.number): \(.title)"'

# Issues by author
gh issue list --author pixiefarm

# Recently updated
gh issue list --json number,title,updatedAt --jq 'sort_by(.updatedAt) | reverse | .[:5] | .[] | "\(.number): \(.title)"'

# Search issue content
gh issue list --search "offline in:body"

Project Board (if using GitHub Projects)

# List projects
gh api repos/:owner/:repo/projects

# Note: GitHub Projects v2 uses GraphQL - see gh project commands
gh project list
gh project view 1