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
- Reduce Implementation Friction: Simplify the process of adding, removing, or modifying Learn GitLab tasks
- Improve Architecture Scalability: Create a more flexible data model that can accommodate future growth
- 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
- 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.
- One row per task/event using
Code Organization
- Create a centralized task registry that serves as the single source of truth
- Implement a more modular approach to task definition and tracking
- Develop a clear API between frontend and backend components
Migration Strategy
- Create new table structure alongside existing one
- Implement data migration to transfer current progress data
- Update application code to use the new structure
- 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