Linear Setup Guide¶

Alternative: See github_projects.md for GitHub Projects configuration

Why Linear?¶

Advantages: - Clean, fast interface (keyboard-first) - Built for software teams - Excellent GitHub integration - Cycles for sprint planning - Roadmaps for planning - Great for async coordination

Tradeoffs: - Costs money ($8/user/month) - Less customizable than Jira - Newer, smaller ecosystem

Workspace Setup¶

Workspace Configuration¶

Name: AudioLab
URL: audiolab.linear.app
Icon: Upload AudioLab logo
Timezone: Primary team timezone

Teams Structure¶

Linear organizes work by Teams. Each team has its own issue tracker.

🎯 Platform Engineering (PLAT)
   - Core infrastructure
   - Build systems
   - DevOps

🎛️ DSP Core (DSP)
   - Audio processing engine
   - Algorithm development
   - Performance optimization

🔌 Plugin SDK (SDK)
   - Plugin framework
   - Developer tools
   - SDK documentation

🖼️ UI Framework (UI)
   - User interface components
   - Design system
   - Accessibility

🧪 Quality & Testing (QA)
   - Test automation
   - Quality assurance
   - Performance testing

🛡️ Security (SEC)
   - Security audits
   - Vulnerability management
   - Compliance

Team prefix: Each team has 2-4 letter prefix (DSP, SDK, UI, etc.) Issue IDs: Format is TEAM-123 (e.g., DSP-42)

Project Hierarchy¶

Workspace (AudioLab)
├── Teams (DSP, SDK, UI, etc.)
│   ├── Projects (Feature sets)
│   │   ├── Issues (Tasks)
│   │   │   └── Sub-issues (Subtasks)
│   ├── Cycles (Sprints)
│   └── Roadmap

Issue Workflow¶

Issue States¶

Backlog states:

📋 Backlog          - Not yet prioritized
🔍 Triage           - Needs review/scoping

Active states:

📅 Todo             - Prioritized, not started
🚧 In Progress      - Actively being worked on
👀 In Review        - Code review, QA

Done states:

✅ Done             - Completed
❌ Canceled         - Won't do

Custom states (optional):

🔴 Blocked          - Can't proceed (blocker identified)
⏸️ On Hold          - Paused (reason noted)
🚀 Deployed         - In production

Issue Types¶

🎯 Feature          - New functionality
🐛 Bug              - Something broken
🔧 Improvement      - Enhancement to existing feature
📚 Documentation    - Docs, README, guides
🧪 Testing          - Test coverage, QA work
🚀 Release          - Release preparation
🔥 Hotfix           - Urgent production fix
💡 Spike            - Research, investigation

Priority Levels¶

🔴 Urgent           - Drop everything (production down)
🟠 High             - Next up, important deadline
🟡 Medium           - Normal priority (default)
🟢 Low              - Nice to have, no rush
⚪ No priority      - Someday/maybe

Guidelines: - Urgent: < 5% of issues (real emergencies only) - High: < 20% of issues (real deadlines) - Medium: ~60% of issues (normal work) - Low: ~15% of issues (improvements) - No priority: Backlog, ideas

Estimation (Points)¶

Use Fibonacci scale for story points:

0 - Trivial         (typo fix, config change)
1 - Very Small      (< 1 hour, obvious solution)
2 - Small           (half day, clear scope)
3 - Medium          (1 day, well-understood)
5 - Large           (2-3 days, some unknowns)
8 - Very Large      (4-5 days, complex)
13 - Huge           (week+, should break down)
21 - Epic           (too big, must break down)

Rules: - Anything > 8 points should be broken down - Estimate relative to each other, not absolute time - Re-estimate if scope changes significantly

See estimation_guidelines.md for details.

Labels¶

Category Labels¶

backend             - Backend code
frontend            - Frontend code
infrastructure      - DevOps, infrastructure
audio-processing    - DSP, audio algorithms
performance         - Performance optimization
security            - Security-related
breaking-change     - Breaking API changes

Platform Labels¶

windows             - Windows-specific
macos               - macOS-specific
linux               - Linux-specific
cross-platform      - Affects all platforms

Domain Labels¶

api                 - Public API
ui                  - User interface
docs                - Documentation
testing             - Tests
ci-cd               - CI/CD pipelines

Best practice: Use 2-4 labels per issue max (be specific, not exhaustive)

Projects¶

Projects group related issues (features, initiatives):

Project Template¶

Name: [Feature] Name Lead: @engineer-name Target date: Q2 2024 Status: In progress

Description:

Brief description of project goals and scope.

Success criteria:
- [ ] Criterion 1
- [ ] Criterion 2
- [ ] Criterion 3

Related:
- Technical design doc: [link]
- PRD: [link]

Example Projects¶

[Feature] VST3 Support
[Feature] Preset Management
[Infrastructure] CI/CD Pipeline
[Improvement] Performance Optimization
[Platform] Linux Port

Cycles (Sprints)¶

Cycle Configuration¶

Duration: 2 weeks (recommended for audio dev)
Start day: Monday
Cooldown: Last Friday for planning next cycle
Auto-archive: Completed issues after 2 weeks

Cycle Planning Process¶

Before cycle starts (Friday before): 1. Review previous cycle completion rate 2. Triage backlog, estimate top issues 3. Draft cycle scope based on capacity 4. Share plan async for feedback

Cycle start (Monday): 1. Finalize cycle scope 2. Assign issues to engineers 3. Mark issues as Todo 4. Announce in Slack/Discord

During cycle: - Daily: Update issue status (manual or via PR) - Mid-cycle: Check progress, adjust if needed - Blockers: Mark as Blocked, note blocker

End of cycle (Friday): 1. Review cycle completion 2. Demo completed work (optional) 3. Move incomplete issues to next cycle or backlog 4. Retrospective (async or sync)

Capacity Planning¶

Per engineer per cycle (2 weeks):

Available hours: 80 hours (2 weeks × 40 hours)
Meetings/email: -10 hours (12.5%)
Code review: -8 hours (10%)
Support/bugs: -8 hours (10%)
Buffer: -8 hours (10%)
───────────────────────────
Development: 46 hours (57.5%)

Story points per engineer: ~13-21 points/cycle (depends on team)

Velocity: Track over 3-4 cycles, use average for planning

Roadmap¶

Quarters Planning¶

Q1 2024 (Jan-Mar)
├── [Platform] Windows Release
├── [Feature] VST3 Support
└── [Infrastructure] CI/CD

Q2 2024 (Apr-Jun)
├── [Platform] macOS Release
├── [Feature] Preset Management
└── [Feature] MIDI Learn

Q3 2024 (Jul-Sep)
├── [Platform] Linux Port
├── [Feature] Modulation System
└── [Improvement] Performance

Q4 2024 (Oct-Dec)
├── [Feature] Advanced UI
├── [Feature] Multi-instance
└── [Release] Version 2.0

Update: Monthly, review progress and adjust

Views¶

Linear supports custom views for filtering issues:

Recommended Views¶

My Issues:

Filter: Assignee is me
       AND State is not Done, Canceled
Sort: Priority (high to low), Updated (recent first)

High Priority:

Filter: Priority is Urgent or High
       AND State is not Done, Canceled
Sort: Priority, Created

Blocked:

Filter: State is Blocked
Sort: Created (oldest first)
Group by: Team

This Cycle:

Filter: Cycle is Current cycle
       AND State is not Canceled
Group by: State
Sort: Priority

Review Needed:

Filter: State is In Review
       AND Assignee is me OR Subscriber is me
Sort: Updated (oldest first)

Save these as team views so everyone can access.

Integrations¶

GitHub Integration (Essential)¶

Setup: 1. Linear → Settings → Integrations → GitHub 2. Connect GitHub account 3. Select repositories to sync 4. Configure auto-linking

Auto-linking: - Branch names: {username}/{issue-key}-{description} → bob/DSP-42-add-fft - Commit messages: Include DSP-42 → Auto-link to issue - PR title: Include DSP-42 → Auto-attach to issue

Auto-updates: - PR opened → Issue moves to In Review - PR merged → Issue moves to Done - Branch pushed → Add comment to issue

Configuration:

{
  "pr_opened": "In Review",
  "pr_merged": "Done",
  "pr_closed_unmerged": "Todo",
  "branch_created": "In Progress"
}

Slack/Discord Integration¶

Notifications: - Issue assigned to you → DM - Issue mentioned you → DM - Issue blocked → Team channel - Cycle complete → Team channel

Commands (Slack):

/linear create [title]           - Create issue
/linear assign DSP-42 @user      - Assign issue
/linear comment DSP-42 [text]    - Add comment
/linear search [query]           - Search issues

CI/CD Integration¶

Link build status to issues:

# In CI workflow, comment on issue
linear comment DSP-42 "✅ Build passed: [link]"

Templates¶

Bug Report Template¶

## Description
[What's broken?]

## Steps to Reproduce
1. Step one
2. Step two
3. Step three

## Expected Behavior
[What should happen?]

## Actual Behavior
[What actually happens?]

## Environment
- OS: Windows 10
- Version: 1.2.3
- DAW: Ableton Live 11

## Logs/Screenshots
[Attach relevant files]

## Severity
- [ ] Crash/data loss
- [ ] Feature broken
- [ ] Minor issue
- [ ] Cosmetic

## Additional Context
[Anything else relevant]

See issue_templates/bug_report.md

Feature Request Template¶

## Problem
[What problem does this solve?]

## Proposed Solution
[How should it work?]

## Alternatives Considered
[What else did you consider?]

## User Stories
- As a [user type], I want [goal] so that [benefit]

## Acceptance Criteria
- [ ] Criterion 1
- [ ] Criterion 2

## Technical Notes
[Any technical considerations]

## Priority
[Why now? Why important?]

See issue_templates/feature_request.md

Technical Spike Template¶

## Goal
[What are we trying to learn?]

## Questions to Answer
- Question 1?
- Question 2?

## Approach
[How will we investigate?]

## Time Box
[How long to spend? Usually 1-2 days max]

## Success Criteria
[What deliverable? Usually a doc or proof-of-concept]

## Findings
[Update when complete]

See issue_templates/technical_spike.md

Automation¶

Linear Workflows (Automations)¶

When issue moves to "In Review": - Assign to random reviewer from team - Add comment: "Ready for review" - Notify in Slack

When issue is "Blocked": - Require comment explaining blocker - Change priority to High - Notify team lead

When issue is stale (no update in 14 days): - Add label: stale - Comment: "This issue has been inactive" - Notify assignee

When PR merged: - Move issue to Done - Add comment with PR link - Add to release notes

Best Practices¶

Writing Good Issues¶

✅ Do: - Clear, specific title - Enough context for anyone to understand - Link to related issues, docs, PRs - Update description as scope evolves - Keep conversation in issue (not Slack)

❌ Don't: - Vague titles ("fix bug", "improve performance") - No description (title-only issues) - Mark done without linking PR - Let issues go stale without updates

Issue Hygiene¶

Weekly: - Close or update stale issues - Re-prioritize based on current goals - Triage new issues

Monthly: - Review backlog, archive outdated issues - Clean up labels, remove unused - Review estimates vs actual time

Keyboard Shortcuts¶

c           Create new issue
/           Quick search
k/j         Navigate up/down
Enter       Open issue
x           Select/deselect issue
u           Assign to me
i           Change priority
s           Change state
v           Move to cycle
Cmd+Shift+k Command palette

Pro tip: Learn keyboard shortcuts, 10x faster than mouse

Reporting & Metrics¶

Team Metrics (Built-in)¶

Velocity: - Story points completed per cycle - Trend over time - Use for capacity planning

Completion rate: - % of cycle issues completed - Target: > 80% - < 70% = over-committing

Cycle time: - Time from Todo → Done - Identify bottlenecks - Optimize for fast feedback

Issue distribution: - By type (feature, bug, etc.) - By priority - Ensure balance

Custom Reports¶

Export issues to CSV/JSON for custom analysis:

Settings → API → Generate token

Use Linear API or GraphQL for custom dashboards.

Cost & Scaling¶

Pricing¶

Free: Unlimited viewers (read-only)
Standard: $8/user/month (full access)
Plus: $14/user/month (advanced features)

Free tier: Good for small teams (<10), limited history

When to Upgrade¶

Team > 5 active developers
Need unlimited issue history
Want advanced automation
SSO/SAML required

Alternatives¶

If cost is concern: - GitHub Projects (free, less powerful) - GitHub Issues (free, basic) - Self-hosted (Plane, Taiga)

Troubleshooting¶

Problem: Too many notifications¶

Solution: Settings → Notifications → Customize per team/project

Problem: Issues not syncing with GitHub¶

Solution: Re-authenticate GitHub integration, check repo permissions

Problem: Velocity inconsistent¶

Solution: Re-calibrate estimates, ensure consistent pointing

Problem: Backlog overwhelming¶

Solution: Archive old issues, create "Icebox" project for ideas

Resources¶

Next Steps: 1. Create Linear workspace 2. Set up teams and workflows 3. Configure GitHub integration 4. Import initial backlog 5. Create issue templates 6. Train team on keyboard shortcuts 7. Run first cycle (2 weeks)