[go: up one dir, main page]

Implement Development Feature Flag for small iterative updates

Overview

With the global_ai_catalog feature flag now enabled in production, we need a safe approach to refactor the AI Catalog agent UI without breaking existing functionality. This issue focuses on implementing a development-type feature flag to enable incremental development of the new agent view/edit page experience.

Context

As discussed in this comment, we need to:

agree on a new approach to work without breaking existing functionality. I am leaning more towards using a new development type feature flag and using small incremental MRs to get to a better UX. This will be pretty straightforward, as we will be working on a completely new page /agents/:id, and we can switch the navigation in 1 go once all is ready.

Proposed Solution

1. Create Development Feature Flag

Create a new development-type feature flag:

# config/feature_flags/development/TBD.yml
---
name: [TBD]
introduced_by_url: [MR URL]
rollout_issue_url: [Issue URL]
milestone: '18.5'
type: development
group: group::workflow catalog
default_enabled: false
Duo Agentic Chat Text

2. New Route Implementation

Implement the new /agents/:id route that will be controlled by the feature flag:

  • New Route: /explore/ai_catalog/agents/:id (show page)
  • Existing Route: Current drawer-based approach
  • Feature Flag Control: Switch between old and new implementations

3. Component Architecture

Create new components for the unified view/edit experience:

ee/app/assets/javascripts/ai/catalog/pages/agents/
├── ai_catalog_agent_show.vue          # New unified show/edit page
├── components/
│   ├── agent_basic_information.vue    # Basic info section
│   ├── agent_access_rights.vue        # Access rights section
│   ├── agent_prompts.vue              # Prompts section
│   └── agent_metadata_panel.vue       # Left sidebar metadata

4. Incremental Development Strategy

Phase 1: Foundation

  • Create development feature flag
  • Set up new route structure
  • Create basic page shell with feature flag guards

Phase 2: Core Components

  • Implement unified show/edit page component
  • Create section-based layout (Basic Info, Access Rights, Prompts)
  • Add left sidebar for metadata/contextual help

Phase 3: Integration

  • Wire up existing GraphQL queries and mutations
  • Implement edit mode toggle functionality
  • Add proper navigation and breadcrumbs

Phase 4: Polish & Testing

  • Add comprehensive test coverage
  • Implement proper error handling
  • Performance optimization and accessibility

5. Feature Flag Implementation

The feature flag should control:

// In router or component logic
if (this.glFeatures.aiCatalogAgentUnifiedView) {
  // Use new unified view/edit page
  return this.$router.push({ name: 'ai-catalog-agent-show', params: { id } });
} else {
  // Use existing drawer approach
  return this.openDrawer(agent);
}

6. Migration Strategy

Once the new experience is complete and tested:

  1. Gradual Rollout: Enable for GitLab team members first
  2. Feedback Collection: Gather internal feedback and iterate
  3. Production Rollout: Enable for all users
  4. Cleanup: Remove old drawer code and feature flag

Technical Considerations

Shared Components

  • Reuse existing GraphQL queries and mutations
  • Maintain compatibility with existing data structures
  • Ensure components are flexible for future project-level integration

URL Structure

  • New URLs should follow Rails conventions (/agents/:id, /agents/:id/edit)
  • Maintain backward compatibility during transition
  • Consider SEO and bookmarking implications

Performance

  • Lazy load components to minimize initial bundle size
  • Implement proper loading states
  • Consider caching strategies for agent data

Acceptance Criteria

Must Have

  • Development feature flag created and functional
  • New /agents/:id route implemented behind feature flag
  • Unified view/edit page with section-based layout
  • Feature flag controls switching between old and new experiences
  • No breaking changes to existing functionality
  • Comprehensive test coverage for new components

Should Have

  • Left sidebar for metadata and contextual help
  • Smooth transitions between view and edit modes
  • Proper error handling and loading states
  • Accessibility compliance (WCAG 2.1 AA)

Could Have

  • Progressive enhancement features
  • Advanced keyboard navigation
  • Customizable section ordering
  • Export/import functionality for agent configurations

Dependencies

  • Existing AI Catalog GraphQL API
  • Current agent data structures and permissions
  • Vue.js router configuration
  • Feature flag infrastructure

Risks & Mitigation

Risk: Feature Flag Complexity

Mitigation: Keep feature flag logic simple and centralized, document switching points clearly

Risk: Code Duplication

Mitigation: Extract shared logic into composables/mixins, plan cleanup phase carefully

Risk: User Confusion During Transition

Mitigation: Ensure consistent UX patterns, provide clear feedback during beta testing

Related Issues

Implementation Notes

This approach allows us to:

  • Develop incrementally without breaking production
  • Test thoroughly before full rollout
  • Maintain existing functionality during development
  • Enable easy rollback if issues arise
  • Collect feedback from internal users first

The development feature flag approach provides a safe path forward while the global_ai_catalog flag remains enabled in production.

Edited by Vanessa Otto