[go: up one dir, main page]

Skip to content

Re-architect Learn GitLab Onboarding Progress to Improve Scalability and Reduce Implementation Friction

Problem Statement

The current implementation of Learn GitLab's onboarding progress tracking has architectural limitations that create friction when adding or modifying tasks and will impede future scaling efforts.

Current Limitations

  • Schema Rigidity: The onboarding_progresses table uses a one-column-per-task design, requiring schema changes for each new task
  • Distributed Logic: Task definitions are duplicated between frontend and backend, violating the Single Source of Truth principle
  • Limited Scalability: The current architecture makes it difficult to expand the onboarding experience
  • Implementation Overhead: Adding or modifying tasks requires changes across multiple components (see example MR)

Goals

Primary Goals

  1. Reduce Implementation Friction: Simplify the process of adding, removing, or modifying Learn GitLab tasks
  2. Improve Architecture Scalability: Create a more flexible data model that can accommodate future growth
  3. Establish Single Source of Truth: Consolidate task definitions to eliminate duplication between frontend and backend

Secondary Goals (Future Consideration)

  • Support both namespace-based and user-based onboarding to enable consistent experiences across SaaS and Self-managed instances

Proposed Solution

Data Model Changes

  1. Replace the current column-per-task design with a normalized table structure:
    • One row per task/event using enum to define task types
    • Maintain namespace_id as a foreign key
    • Completion time will be driven off the created_at column for each row.

Code Organization

  1. Create a centralized task registry that serves as the single source of truth
  2. Implement a more modular approach to task definition and tracking
  3. Develop a clear API between frontend and backend components

Migration Strategy

  1. Create new table structure alongside existing one
  2. Implement data migration to transfer current progress data
  3. Update application code to use the new structure
  4. Remove legacy table after successful transition

Implementation Considerations

  • Backward compatibility during transition
  • Performance impact of the new query patterns
  • Testing strategy to ensure data integrity
  • Data analytics migration to new design/table.

Success Metrics

  • Reduced time to implement new Learn GitLab tasks
  • Fewer files changed when modifying the onboarding experience
  • Improved developer experience when working with onboarding features
Edited by Doug Stull