courseworx/docs/Linear-Integration-Guide.md

Linear Integration Guide for CourseWorx

🚀 Linear + GitHub Integration Setup

This guide shows how to integrate your new Linear account with CourseWorx for advanced project management, replacing traditional GitHub Issues with Linear's powerful workflow system.

🎯 Why Linear for CourseWorx?

Linear provides superior project management compared to GitHub Issues:

• Spec Management: Better than GitHub's basic issue templates
• Sprint Planning: Advanced roadmap and milestone tracking
• Team Collaboration: Superior to GitHub Projects
• Issue Tracking: More sophisticated than GitHub Issues
• Requirements Management: Perfect for spec kit workflows

📋 Linear Setup Steps

1. Initial Linear Configuration

Connect Linear to GitHub

1. Go to Linear Settings: https://linear.app/settings/integrations
2. Add GitHub Integration:
   • Click "Add Integration" → GitHub
   • Authorize Linear to access your repositories
   • Select your CourseWorx repository

Configure Linear Workspace

Workspace Name: CourseWorx Development
Team Name: CourseWorx Team
Projects: 
  - CourseWorx Core Platform
  - Mobile Development
  - Feature Specifications

2. Linear Project Structure

Teams Setup

Teams:
  - CourseWorx Core:
      Description: Main platform development
      Key: CW
      
  - Mobile Team:
      Description: Mobile and cross-platform work  
      Key: MOB
      
  - Specifications:
      Description: Requirements and spec management
      Key: SPEC

Issue Types Configuration

Issue Types:
  - Epic: 🎯 Large features or initiatives
  - Feature: ✨ New functionality 
  - Bug: 🐛 Issues and fixes
  - Improvement: 🔧 Enhancements
  - Spec: 📋 Requirements and specifications
  - Mobile: 📱 Mobile-specific work
  - Backend: ⚙️ Server-side development
  - Frontend: 🎨 UI/UX development

Labels Setup

Priority Labels:
  - Critical: 🔴 System down, blocking
  - High: 🟠 Important for current sprint  
  - Medium: 🟡 Standard priority
  - Low: 🟢 Nice to have

Component Labels:
  - authentication: 🔐 Auth system
  - courses: 📚 Course management
  - enrollment: 👥 Student enrollment
  - attendance: 📅 Attendance tracking
  - assignments: 📝 Assignment system
  - ui-ux: 🎨 User interface
  - database: 💾 Data layer
  - api: 🔌 Backend API
  - mobile: 📱 Mobile features
  - security: 🛡️ Security related

3. Workflow States

Standard Workflow

States:
  Todo: 📋 Ready for development
  In Progress: 🔄 Currently being worked on  
  In Review: 👀 Code review or testing
  Testing: 🧪 QA and testing phase
  Done: ✅ Completed and deployed
  Cancelled: ❌ No longer needed

Spec-Specific Workflow

Spec States:
  Draft: 📝 Initial requirements gathering
  Review: 🔍 Stakeholder review
  Approved: ✅ Ready for development
  In Development: 🔧 Being implemented
  Testing: 🧪 Spec validation
  Complete: 🎯 Spec fully implemented

4. Linear CLI Setup

Installation

# Install Linear CLI
npm install -g @linear/cli

# Authenticate with Linear
linear auth

# Set up for CourseWorx repository
cd /workspace
linear init

Basic Commands

# Create issue from command line
linear issue create --title "Add mobile responsive header" --team CW

# Link commits to Linear issues
git commit -m "CW-123: Implement mobile header responsive design"

# View current sprint
linear issues --status "In Progress"

# Create spec issue
linear issue create --title "User Authentication Specification" --team SPEC --type Spec

5. GitHub Integration Configuration

Automatic Issue Linking

Linear automatically links GitHub commits and PRs when you:

# Use Linear issue ID in commit messages
git commit -m "CW-45: Fix mobile navigation bug"

# Use Linear ID in PR titles
"CW-67: Add course enrollment mobile UI"

# Use Linear ID in branch names
git checkout -b "feature/CW-89-mobile-attendance"

Linear Bot Configuration

Add to your GitHub repository settings:

# .github/linear.yml
linear:
  webhook_url: "https://webhook.linear.app/github"
  auto_assign: true
  sync_labels: true
  close_on_merge: true

6. Spec Management Workflow

Creating Specifications

# Linear Issue Template for Specs

Title: [SPEC] Mobile Attendance System Requirements
Type: Spec
Team: Specifications
Priority: High

## Overview
Brief description of the feature/system

## User Stories
- As a trainee, I want to check in via mobile...
- As a trainer, I want to view attendance on mobile...

## Acceptance Criteria  
- [ ] Mobile UI is responsive on all devices
- [ ] QR code scanning works in mobile browsers
- [ ] Offline attendance tracking capability

## Technical Requirements
- React Native components
- PWA offline support  
- Integration with existing backend

## Dependencies
- Relates to: CW-23 (Backend attendance API)
- Blocks: CW-45 (Mobile dashboard)

## Design Assets
- Link to Figma designs
- Screenshots or mockups

Spec Review Process

1. Create Spec Issue: Use SPEC team in Linear
2. Stakeholder Review: Assign to product owner
3. Technical Review: Assign to lead developer
4. Approval: Move to "Approved" state
5. Break Down: Create development issues (CW-xxx)
6. Track Progress: Monitor implementation

7. Integration with CourseWorx Development

Project Cycles

Cycles (2-week sprints):
  Sprint 1: Mobile UI Foundation
    - CW-101: Responsive navigation 
    - CW-102: Mobile course cards
    - CW-103: Touch-friendly buttons
    
  Sprint 2: Mobile Attendance
    - CW-201: QR code scanner
    - CW-202: Offline attendance
    - CW-203: Sync functionality

  Sprint 3: Mobile Course Management  
    - CW-301: Mobile course creation
    - CW-302: Content upload on mobile
    - CW-303: Assignment management

Roadmap Planning

Roadmap Items:
  Q1 2024: Mobile Platform Foundation
    - Complete responsive design
    - Implement PWA features  
    - Basic mobile functionality
    
  Q2 2024: Advanced Mobile Features
    - Offline capabilities
    - Push notifications
    - Advanced touch interactions
    
  Q3 2024: Cross-Platform Optimization
    - Performance improvements
    - Desktop-mobile sync
    - Advanced collaboration tools

8. Linear Shortcuts and Productivity

Keyboard Shortcuts

Essential Shortcuts:
  C: Create new issue
  /: Search issues
  K: Command palette  
  G + I: Go to issues
  G + R: Go to roadmap
  G + P: Go to projects

Quick Actions

Issue Management:
  Ctrl/Cmd + Enter: Create issue
  E: Edit current issue
  A: Assign to someone
  L: Add labels
  S: Change status
  P: Set priority

9. Reporting and Analytics

Linear Insights

Track Progress:
  - Velocity: Issues completed per sprint
  - Cycle time: Time from start to completion  
  - Team performance: Individual and team metrics
  - Burndown: Sprint progress visualization

Custom Views

Useful Views:
  - My Mobile Issues: assigned:me label:mobile
  - Current Sprint: cycle:"Current Sprint"  
  - Specs Pending: team:SPEC state:"Review"
  - High Priority: priority:high
  - Mobile Bugs: type:bug label:mobile

10. Migration from GitHub Issues

Export Existing Issues

# If you have existing GitHub issues to migrate
# Use Linear's GitHub import feature:
# 1. Go to Settings > Import > GitHub Issues  
# 2. Select your CourseWorx repository
# 3. Choose which issues to import
# 4. Map labels and assignees

Maintaining GitHub Issues Temporarily

Parallel Usage:
- Use GitHub Issues for: Bug reports from users
- Use Linear for: Development planning, specs, sprints
- Eventually: Migrate all to Linear as team adopts it

🎯 Next Steps

1. Set up Linear Account: Create workspace and teams
2. Configure GitHub Integration: Connect repositories
3. Import Existing Work: Migrate current issues/projects
4. Create First Spec: Start with mobile attendance feature
5. Team Onboarding: Train team on Linear workflow
6. Iterate: Refine workflow based on usage

💡 Linear Best Practices for CourseWorx

Issue Naming Convention

Format: [Component] Brief description
Examples:
  - [Mobile] Add responsive navigation header
  - [Auth] Implement mobile login flow
  - [Spec] Course enrollment requirements  
  - [API] Mobile attendance endpoints

Issue Relationships

Use Relations:
  - Blocks: This issue prevents another from starting
  - Relates to: Connected but not dependent
  - Duplicates: Same issue reported multiple times
  - Parent/Child: Epic breakdown structure

Estimation

Story Points (Fibonacci):
  - 1: Small bug fix or minor UI tweak
  - 2: Small feature, few hours of work
  - 3: Medium feature, half day of work  
  - 5: Large feature, full day of work
  - 8: Complex feature, multiple days
  - 13: Epic that should be broken down

---

Linear provides the perfect project management foundation for CourseWorx's cross-platform development workflow.