GitHub Projects Configuration¶
Alternative: See linear_setup.md for Linear setup
Why GitHub Projects?¶
Advantages: - Free with GitHub - Tight integration with issues/PRs - Simple, familiar interface - No additional accounts needed - Customizable views
Tradeoffs: - Less powerful than dedicated tools - Limited automation - No native estimation/velocity tracking - Newer (less mature than Linear/Jira)
Best for: Teams already using GitHub, budget-conscious, simple workflows
Project Types¶
GitHub offers two project types:
Classic Projects (Legacy)¶
- Kanban board style
- Per-repository or organization-wide
- Limited features
- Recommendation: Use new Projects (below)
Projects (New, Beta)¶
- Table and board views
- Custom fields
- Automation
- Cross-repository
- Recommendation: Use this
Creating a Project¶
Organization-Level Project¶
1. GitHub → Your Organization → Projects
2. New Project
3. Choose template:
- Team backlog (recommended for development)
- Bug triage
- Roadmap
- Start from scratch
4. Name: "AudioLab Development"
5. Create project
Repository-Level Project¶
1. GitHub → Repository → Projects
2. Link project → Create new project
3. Follow same steps as above
Recommendation: Organization-level for cross-repo coordination
Project Setup¶
Views¶
Projects support multiple views of the same data:
1. Board View (Kanban)¶
Columns:
📋 Backlog - Not started, prioritized
🔍 Triage - Needs review
📅 Todo - Ready to start
🚧 In Progress - Being worked on
👀 In Review - Code review
✅ Done - Completed
❌ Canceled - Won't do
Automation: - New issues → Backlog - PR opened → In Review - PR merged → Done
2. Table View (Spreadsheet)¶
Columns:
- Title (built-in)
- Status (built-in)
- Assignees (built-in)
- Labels (built-in)
- Priority (custom)
- Size (custom)
- Sprint (custom)
- Team (custom)
Use: Bulk editing, sorting, filtering
3. Roadmap View (Timeline)¶
Use: High-level planning, visualize schedule
Custom Fields¶
Add custom fields to track additional metadata:
Priority (Single Select)¶
🔴 Urgent - P0, drop everything
🟠 High - P1, next up
🟡 Medium - P2, normal priority
🟢 Low - P3, nice to have
⚪ None - Not prioritized
Size (Single Select)¶
XS - Extra Small (< 1 hour)
S - Small (half day)
M - Medium (1 day)
L - Large (2-3 days)
XL - Extra Large (4-5 days)
XXL - Huge (week+, should break down)
Sprint (Text or Iteration)¶
Format: YYYY-Wxx
Examples: 2024-W14, 2024-W15
Or use Iteration field:
Duration: 2 weeks
Start: Monday
Team (Single Select)¶
Type (Labels work, but can also use custom field)¶
Issue Templates¶
GitHub Issues can have templates:
Setup¶
Bug Report Template¶
See issue_templates/bug_report.md
name: Bug Report
about: Report a bug or unexpected behavior
title: "[BUG] "
labels: bug, triage
assignees: ''
Feature Request Template¶
See issue_templates/feature_request.md
name: Feature Request
about: Suggest a new feature or enhancement
title: "[FEATURE] "
labels: feature, triage
assignees: ''
Technical Spike Template¶
See issue_templates/technical_spike.md
name: Technical Spike
about: Investigation or research task
title: "[SPIKE] "
labels: spike
assignees: ''
Location: .github/ISSUE_TEMPLATE/ in repository
Labels Strategy¶
Priority Labels¶
priority: urgent - P0, critical
priority: high - P1, important
priority: medium - P2, normal
priority: low - P3, nice to have
Type Labels¶
type: bug - Something broken
type: feature - New functionality
type: improvement - Enhancement
type: docs - Documentation
type: testing - Tests
type: hotfix - Urgent production fix
Area Labels¶
area: audio - Audio processing
area: ui - User interface
area: platform - Platform-specific
area: api - Public API
area: performance - Performance
area: security - Security
Platform Labels¶
Status Labels (if not using Projects)¶
status: blocked - Blocked by something
status: on-hold - Paused
status: wont-fix - Closing, won't fix
Color scheme: - Priority: Red (urgent) → Yellow (medium) → Green (low) - Type: Blue shades - Area: Purple shades - Platform: Orange shades
Automation¶
Built-in Workflows¶
Enable in Project → Settings → Workflows:
Item added to project: - Set status to: Backlog
Item closed: - Set status to: Done
Pull request merged: - Set status to: Done
Code changes requested: - Set status to: In Progress (from In Review)
Pull request approved: - Set status to: In Review (waiting for merge)
GitHub Actions for Advanced Automation¶
Auto-label PRs¶
# .github/workflows/auto-label.yml
name: Auto Label
on:
pull_request:
types: [opened]
jobs:
label:
runs-on: ubuntu-latest
steps:
- uses: actions/labeler@v4
with:
repo-token: "${{ secrets.GITHUB_TOKEN }}"
# .github/labeler.yml
'area: audio':
- src/audio/**/*
- include/audio/**/*
'area: ui':
- src/ui/**/*
- include/ui/**/*
'type: docs':
- docs/**/*
- '**/*.md'
Auto-add to project¶
# .github/workflows/auto-add-to-project.yml
name: Add to Project
on:
issues:
types: [opened]
pull_request:
types: [opened]
jobs:
add-to-project:
runs-on: ubuntu-latest
steps:
- uses: actions/add-to-project@v0.4.0
with:
project-url: https://github.com/orgs/audiolab/projects/1
github-token: ${{ secrets.ADD_TO_PROJECT_PAT }}
Stale issue handler¶
# .github/workflows/stale.yml
name: Mark Stale Issues
on:
schedule:
- cron: '0 0 * * *' # Daily
jobs:
stale:
runs-on: ubuntu-latest
steps:
- uses: actions/stale@v8
with:
repo-token: ${{ secrets.GITHUB_TOKEN }}
stale-issue-message: 'This issue has been inactive for 30 days.'
days-before-stale: 30
days-before-close: 7
stale-issue-label: 'stale'
Milestones¶
Use GitHub Milestones for releases or sprints:
Create Milestone¶
Repository → Issues → Milestones → New milestone
Title: v1.2.0 or Sprint 14
Description: Release notes or sprint goals
Due date: 2024-04-15
Add Issues to Milestone¶
Track Progress¶
- Milestone page shows completion percentage
- Open vs closed issues
- Link to milestone in project board
Sprint Planning with Projects¶
Two-Week Sprint Setup¶
Create Iteration field:
Project → Settings → Custom fields → New field
Type: Iteration
Name: Sprint
Duration: 2 weeks
Start day: Monday
Sprint workflow: 1. Planning (Friday before): Add issues to next sprint 2. Sprint start (Monday): Move issues to Todo 3. Daily updates: Move issues through workflow 4. Sprint end (Friday): Review completion, retrospective
Views for sprint:
Current Sprint (Board):
Sprint Planning (Table):
Estimation¶
GitHub Projects doesn't have built-in estimation, but you can add custom fields:
Story Points (Number field)¶
Calculate velocity: - Export table view to CSV - Sum points for closed issues in sprint - Manual tracking in spreadsheet
T-Shirt Sizing (Single Select)¶
See estimation_guidelines.md for details.
Roadmap Planning¶
Quarterly View¶
Create custom fields:
- Quarter (Single select): Q1 2024, Q2 2024, etc.
- Start Date (Date)
- Target Date (Date)
Roadmap view:
View type: Roadmap
Layout: Timeline
Start date: Start Date field
End date: Target Date field
Group by: Quarter
Use: Visualize major features and releases
Integrations¶
Slack/Discord Notifications¶
GitHub Actions to post updates:
# .github/workflows/notify-slack.yml
name: Notify Slack
on:
issues:
types: [opened, closed]
jobs:
slack:
runs-on: ubuntu-latest
steps:
- name: Send to Slack
uses: slackapi/slack-github-action@v1
with:
webhook-url: ${{ secrets.SLACK_WEBHOOK }}
payload: |
{
"text": "Issue ${{ github.event.action }}: ${{ github.event.issue.title }}",
"blocks": [
{
"type": "section",
"text": {
"type": "mrkdwn",
"text": "*<${{ github.event.issue.html_url }}|#${{ github.event.issue.number }} ${{ github.event.issue.title }}>*"
}
}
]
}
API Access¶
Use GitHub API or GraphQL for custom integrations:
# Get project data
gh api graphql -f query='
query {
organization(login: "audiolab") {
projectV2(number: 1) {
items(first: 100) {
nodes {
id
content {
... on Issue {
title
state
}
}
}
}
}
}
}'
Best Practices¶
Issue Writing¶
✅ Good issue:
Title: Add SIMD optimization to FFT implementation
Description:
Currently, FFT is scalar-only and 4x slower than competitors.
Goal: Add SSE4/AVX2 SIMD paths for ~4x speedup
Acceptance criteria:
- [ ] SSE4 implementation
- [ ] AVX2 implementation
- [ ] Runtime CPU detection
- [ ] Benchmarks show >= 3x improvement
- [ ] Tests pass on all platforms
Related: #123 (performance tracking issue)
Benchmark results: [link]
❌ Bad issue:
Project Hygiene¶
Daily: - Update issue status as you work - Move cards on board - Comment on blockers
Weekly: - Triage new issues (review, prioritize, assign) - Close stale issues - Update sprint progress
Monthly: - Review backlog, archive old issues - Update roadmap - Clean up labels
Comparison: GitHub Projects vs Linear¶
| Feature | GitHub Projects | Linear |
|---|---|---|
| Cost | Free | $8/user/month |
| GitHub integration | Native | Excellent |
| Interface | Good | Excellent |
| Keyboard shortcuts | Basic | Extensive |
| Estimation | Manual (custom fields) | Built-in |
| Velocity tracking | Manual | Automatic |
| Automation | Good (Actions) | Excellent |
| Roadmap | Basic timeline | Advanced |
| Mobile | Web only | Native apps |
| Learning curve | Low | Low |
Recommendation: - GitHub Projects: Budget-conscious, simple needs, already on GitHub - Linear: Team > 5, need advanced features, willing to pay
Keyboard Shortcuts¶
Note: Less extensive than Linear, but covers basics
Templates for Success¶
Weekly Triage Meeting Agenda¶
## New Issues (Triage label)
- Review each issue
- Set priority
- Estimate size
- Assign or leave in backlog
## Blocked Issues
- Review blockers
- Unblock or escalate
## Sprint Progress
- Completion rate
- Any concerns?
Sprint Planning Template¶
## Sprint Goals
1. [Goal 1]
2. [Goal 2]
## Capacity
- Engineers: 3
- Total points: ~40 (13 pts/person)
## Committed Issues
- [ ] #123 - Feature A (8 pts)
- [ ] #124 - Feature B (5 pts)
- [ ] #125 - Bug fix (3 pts)
...
## Stretch Goals (if ahead)
- [ ] #126 - Nice to have (5 pts)
Retrospective Template¶
## What went well? ✅
## What didn't go well? ❌
## Action items 🎯
- [ ] Action 1 (Owner: @user)
- [ ] Action 2 (Owner: @user)
Resources¶
Next Steps: 1. Create organization project 2. Set up custom fields (Priority, Size, Sprint) 3. Create issue templates 4. Configure automation workflows 5. Import existing issues 6. Train team on workflow 7. Run first sprint