Linear Documentation #

Linear is our primary task management and issue tracking system. This document provides guidance on how to effectively use Linear within our workflow, its integrations with other tools, and helpful tips to increase productivity.

Getting Started with Linear #

Access and Onboarding #

• Access: New team members should request access to our Linear workspace from their team lead
• Workspace URL: https://linear.app/tofu-bonsai
• Mobile Apps: Available for iOS and Android

Core Concepts #

Linear organizes work in a hierarchical structure:

1. Initiatives: Large bodies of work (typically spanning multiple cycles)
2. Projects: Focused efforts with a defined scope and timeline
3. Milestones: Key delivery dates or goals
4. Issues: Individual tasks to be completed
5. Cycles: Time-boxed periods (typically 1-2 weeks) for completing issues

Keyboard Shortcuts and Power User Tips #

Essential Shortcuts #

• c: Create new issue
• f: Global search
• g + i: Go to issues
• g + p: Go to projects
• g + r: Go to roadmap
• g + m: Go to my issues
• g + t: Go to teams
• g + c: Go to current cycle
• e: Edit current issue
• a: Assign current issue
• l: Add label to current issue
• s: Change status of current issue
• t: Add issue to cycle
• p: Add issue to project
• /: Focus search bar

Power User Tips #

1. Custom Views: Create and save custom issue views with specific filters
2. Bulk Actions: Select multiple issues with Shift+click to update them simultaneously
3. Templates: Use issue templates for common task types
4. Slash Commands: In issue descriptions and comments:
   • /assign @user: Assign to specific user
   • /due date: Set due date
   • /estimate X: Set estimate
   • /priority urgent|high|medium|low: Set priority
   • /project Project Name: Add to project
   • /label Label Name: Add label
5. Markdown Support: Use markdown formatting in descriptions and comments
6. Timeline View: Switch to timeline view for visual project planning
7. List View Sorting: Click column headers to sort issues by priority, title, etc.
8. Filter Syntax: Use advanced filters like assignee:me status:in-progress
9. Recurring Issues: Set up repeating issues for routine tasks
10. Import/Export: Use CSV import/export for batch operations

AI-Powered Issue Creation with Cursor #

We leverage Cursor’s AI capabilities with our Linear workflow through “prompt” type issue templates:

1. Prompt Templates: Select the “prompt” template when creating a new issue
2. Cursor Integration Workflow:
   • Create a new issue in Linear
   • Select the “prompt” type template
   • Copy the template content and paste it into Cursor chat
   • Replace the <feature> tag with necessary details and context about what needs to be built
   • Cursor will generate comprehensive issue content that accounts for our codebase
   • Copy the generated content back into the Linear issue
   • Review and modify as needed

This approach produces higher quality issue descriptions since Cursor understands our codebase structure, dependencies, and patterns, resulting in more accurate task descriptions and acceptance criteria.

Workflow and Best Practices #

Initiatives #

Initiatives represent strategic, high-level objectives. They help organize related projects and maintain alignment with business goals.

• Creating Initiatives: Navigate to the Initiatives tab and click “New Initiative”
• Best Practices:
  • Keep initiative descriptions high-level but clear
  • Link to relevant product/design documents
  • Regularly update progress
  • Associate relevant projects and issues

Projects #

Projects group related issues that contribute to a specific deliverable.

• Creating Projects: Navigate to the Projects tab and click “New Project”
• Project States:
  • Planned
  • Started
  • Paused
  • Completed
  • Canceled
• Best Practices:
  • Set clear start/end dates
  • Define concrete success criteria
  • Assign a project lead
  • Link to an initiative if applicable
  • Use project updates to provide regular status reports

Milestones #

Milestones represent significant points in time, often deliveries or launches.

• Creating Milestones: Navigate to Roadmap view and click “New Milestone”
• Best Practices:
  • Use consistent naming conventions
  • Set realistic target dates
  • Link related projects and issues
  • Update status as progress is made

Issues #

Issues are the smallest unit of work in Linear.

• Creating Issues: Click “+” in the top-right corner or use the c keyboard shortcut

• Issue Structure:

  • Title: Clear, concise description of the task
  • Description: Detailed explanation including acceptance criteria
  • Priority: Urgent, High, Medium, Low
  • Labels: For categorization
  • Assignee: The person responsible
  • Projects/Initiatives: Associated higher-level groupings
  • Cycle: The timeframe for completion

• Issue States:

  Linear issues move through these states during development:

  • Backlog: Issues that are planned but not yet ready to start
  • Todo: Issues ready to be picked up by a developer
  • In Progress: Developer is actively working on the issue
  • In Review: Code review in progress (includes both engineer and CS team reviews)
  • In Dev: Deployed to development environment (automated)
  • Needs Revert: Issues found in main branch that require reverting or hotfix
  • Ready for Release: Managed by Product team, ready for production
  • Done: Fully deployed and verified in production
  • Canceled: Issue was canceled and will not be completed

• Best Practices:

  • Write clear, actionable titles
  • Include sufficient context in descriptions
  • Add sub-issues for complex tasks
  • Link to relevant resources (designs, docs)
  • Set realistic estimates
  • Keep status updated

Cycles #

Cycles are time-bound periods for completing a set of issues.

• Cycle Structure: Typically 1-2 weeks in length
• Cycle Planning:
  • Review the backlog
  • Prioritize issues
  • Consider team capacity
  • Add issues to the upcoming cycle
• Active Cycle Management:
  • Daily updates on issue status
  • Identify blockers early
  • Adjust scope if necessary
• Cycle Completion:
  • Review completed issues
  • Document learnings
  • Move incomplete issues to the next cycle

Integrations #

GitHub Integration #

Our Linear workspace is integrated with GitHub to streamline development workflow:

• Issue-PR Linking: Linear issues are automatically linked to related GitHub PRs
• PR Status: The status of linked PRs appears in Linear issues
• Branch Creation: Create GitHub branches directly from Linear issues
• Automatic Status Updates: When a PR is merged, the linked issue status is updated

Usage Tips:

• Include the issue ID (e.g., PROJECT-123) in commit messages and PR titles
• Use Linear’s GitHub action in PRs via /linear
• Create branches from Linear with the “Create branch” button

Slack Integration #

Linear integrates with our Slack workspace to provide notifications and enable actions:

• Notifications:

  • New issue assignments
  • Mentions
  • Status changes
  • Comments
  • Cycle updates
  • Project updates

• Commands:

  • /linear create: Create a new issue
  • /linear search: Search for issues
  • /linear my issues: List your assigned issues
  • /linear projects: List active projects

• Configuring Notifications: Adjust your personal notification settings in Linear > Settings > Notifications

Development Workflow with Linear #

Our team uses Linear to manage the full software development lifecycle — from planning to production deployment. This section explains how Linear integrates with our development process.

Picking Up an Issue #

When you’re ready to start work:

1. Check Assignment: Ensure the issue is assigned to you
2. Verify Status: Issue should be in Backlog or Todo status
3. Copy Branch Name: Click the branch icon in Linear to copy the Git branch name
4. Update Status: Change issue status to In Progress
5. Create Branch: Create your feature branch using the copied name

git checkout main
git pull
git checkout -b <copied-branch-name>

Example branch name: username/eng-1234-add-dark-mode

Creating a Pull Request #

After developing your feature:

1. Push Your Branch:

   git push -u origin <branch-name>
   

2. Create Draft PR on GitHub:

   • Add clear description of changes
   • Link Linear issue (automatically linked if using Linear branch name)
   • Post PR link to #eng-pr-review on Slack
   • Linear issue status automatically updates to In Review when PR is opened

3. Preview Environment (if issue has preview label):

   • Draft PR automatically creates preview environment
   • Add “CS Needs Testing” label to request CS team review
   • CS team can also add this label from Linear (automatically syncs to GitHub)

Working with Preview Environments #

Preview environments allow the CS team to test features before merging:

• Each commit triggers automatic rebuild (10-13 minutes)
• Track build progress in Coder deployment logs
• To request CS team review, add the “CS Needs Testing” label to your GitHub PR
• Wait until preview is fully deployed before adding the label

Important: Do not add “CS Needs Testing” label until the preview environment is fully accessible.

Review and Merge Flow #

Your issue moves through these stages during review and deployment:

CS Team Review Process #

When you need CS team to review your PR with preview environment:

1. Request Review: Add the “CS Needs Testing” label to your GitHub PR
   • Alternatively, CS team can add the label in Linear (automatically syncs to GitHub)
2. CS Team Reviews: CS team tests the preview and updates the label to either:
   • “CS Approved”: Feature approved (tofu-tofie bot approves the PR)
   • “CS Needs Fix”: Issues found (tofu-tofie bot requests changes)
3. Address Feedback: If “CS Needs Fix”, make fixes and push new commits
4. Re-request Review: After fixes, change label back to “CS Needs Testing”
5. Merge: Once approved by all reviewers, merge into main using squash merge

Merging Your PR #

Once your PR is approved:

1. Verify: All CI checks pass
2. Review: All comments addressed
3. Merge: Use squash merge to merge into main
4. Cleanup: Delete your branch after merging
5. Automatic: Linear updates issue status to In Dev

Handling Reverts or Hotfixes #

If your issue status changes to Needs Revert:

Option 1: Quick Revert

# Revert through GitHub UI
# Go to PR → Revert button → Create revert PR → Merge

Option 2: Create Hotfix

git checkout main
git pull
git checkout -b <username>/hotfix-<issue-number>-<description>
# Make fixes
git push -u origin <branch-name>
# Create PR and follow normal review process

Integration with GitHub #

Linear automatically tracks GitHub activity:

• Branch Creation: Create branches directly from Linear issues
• PR Linking: Include issue ID (e.g., ENG-123) in commit messages and PR titles
• Status Updates: When PR is merged, Linear updates issue status automatically
• PR Status: See PR status directly in Linear issues

Best Practice: Always use the Linear branch name generator to ensure proper linking.

Best Practices for Our Team #

General Best Practices #

1. Issue Creation Standard: All development work should have a corresponding Linear issue
2. Daily Updates: Update the status of your in-progress issues daily
3. Cycle Planning: Participate in cycle planning meetings and prioritization
4. Issue Quality: Include sufficient details in issues for anyone to understand and work on them
5. Cross-functional Visibility: Use mentions to pull in stakeholders from other teams
6. Documentation: Link to design files, technical specs, and other documentation in issues
7. Estimates: Provide realistic estimates and update them if scope changes
8. Labels: Use consistent labeling to help with filtering and reporting
9. Comments: Use comments to provide progress updates and ask clarifying questions
10. Blockers: Flag blockers early by changing priority and mentioning relevant team members

Preview Label Requirements #

When your issue has a preview label:

• CS Team Review: Add “CS Needs Testing” label to request CS team review
• Status Management: Keep issue status updated (In Progress → In Review)
• Communication: Comment on PR with preview URL and testing instructions
• Label-Based Approval: CS team uses labels to approve/request changes
• Bot Integration: tofu-tofie bot automatically approves or requests changes based on CS team labels

GitHub Label Workflow #

Our workflow uses GitHub labels to manage CS team reviews:

Labels managed by Engineers/CS:

• “CS Needs Testing”: Request CS team review (can be added from GitHub PR or Linear)
• “CS Approved”: CS team approved (triggers tofu-tofie bot approval)
• “CS Needs Fix”: CS team requests changes (triggers tofu-tofie bot change request)

Label Synchronization:

• Labels added in Linear automatically sync to GitHub PR
• Labels added in GitHub PR are visible in Linear issue

Issue Status Management #

Developer Responsibilities:

• Update status when picking up work (Backlog → In Progress)
• Add “CS Needs Testing” label to PR if CS team review is needed
• Address feedback and update labels as needed
• Merge when approved (automatically becomes In Dev)

Automated Updates:

• In Review: Automatically set when PR is opened
• In Dev: Automatically set when PR merged to main
• Ready for Release: Set by Product team
• Done: Set by Product team after production deployment

CS Team Actions:

• Review features in preview environments
• Update labels to “CS Approved” or “CS Needs Fix”
• tofu-tofie bot automatically approves/requests changes based on label