9 KiB
9 KiB
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
- Go to Linear Settings: https://linear.app/settings/integrations
- 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
- Create Spec Issue: Use SPEC team in Linear
- Stakeholder Review: Assign to product owner
- Technical Review: Assign to lead developer
- Approval: Move to "Approved" state
- Break Down: Create development issues (CW-xxx)
- 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
- Set up Linear Account: Create workspace and teams
- Configure GitHub Integration: Connect repositories
- Import Existing Work: Migrate current issues/projects
- Create First Spec: Start with mobile attendance feature
- Team Onboarding: Train team on Linear workflow
- 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.