Adds configuration approach to work item types design doc

Marc Saleikorequested to merge
ms/cwits/add-configuration-approach-to-design-doc into main

Why is this change being made?

Documents the configuration-based approach for handling work item type behavior and special type handling (Service Desk, Incident Management) in the Configurable Work Item Types design document.

After team discussion (Slack thread), we decided against introducing separate "capability" and "configuration" concepts in favor of a unified configuration approach. This MR adds documentation for:

AI Summary of the discussion in Slack (for the record)

Participants

@msaleiko @kassio @deepika.guliani @nicolasdular @acroitor @engwan

Initial Proposal

Marc proposed replacing hard-coded type checks with two concepts:

  1. Capabilities - Exclusive features only one type can have per namespace (e.g., :service_desk, :incident_management)

    • Usage: type.capable_of?(:service_desk)
    • For add-on features with mandatory widgets that aren't widgetized
    • Only ONE type can have each capability

  2. Configurations - Behavior settings multiple types can share (e.g., use_legacy_view, group_level)

    • Passed via GraphQL to frontend
    • Simple behavioral flags

Team Feedback

Deepika and Kassio preferred configuration-only approach:

  • Concerned capabilities still felt like type checks ("checking instance of rather than type")
  • Worried about architectural complexity maintaining two concepts
  • Suggested configurations could handle both use cases - exclusive features would just be configurations that only exist on a single type

Nicolas also voted for configuration-only for flexibility and less hardcoding.

Alexandru questioned whether capabilities differ meaningfully from base_type checks, suggesting keeping base_type checks for now and defaulting new custom types to issue base type.

Nick Leonard asked whether the capability architecture would make it difficult to expand functionality to >1 type later (answer: technically no, capabilities could be appended).

Marc's Clarification

Marc explained the distinction was about:

  • Capabilities: Type identity with mandatory widget contracts (e.g., Service Desk requires specific widgets like notes, email_participants, requestor)
  • Configurations: Simple behavior flags

He argued for centralizing logic rather than scattered type checks throughout the app, enabling a "duck typing" approach where code asks "can it do X?" rather than "what type is it?"

Kassio's Counter-Argument

Kassio suggested capabilities seemed like "a set of configurations" - e.g., Service Desk capability could be required_widgets + created_by_email configurations bundled together. Preferred simpler architecture that could mix/match configurations as requirements evolve.

Final Decision

Marc conceded after further reflection:

  • Only 2 exclusive cases (Service Desk, Incidents) don't warrant separate architectural concept
  • For converted custom types, can check converted_from_system_defined_identifier (no DB queries)
  • Will keep configuration approach and use type checks for "capabilities" (abstracted in methods)
  • Required widgets can be part of system-defined type definitions

Heinrich supported this, noting eventually everything should be widgetized, so very few type checks should remain long-term.

Marc's remaining concern: Frontend still needs "something" to display incidents/tickets with connected features. Considered using configuration flags (e.g., configured_for?(:service_desk)) plus type provider for lookups (WorkItems::TypeProvider.new(root).service_desk_type), though noted it "presses two concepts into one."

Outcome

Single configuration-based approach with:

  • Configuration flags for quick checks
  • Type provider pattern for finding designated types (or different name/location...)
  • Limited, abstracted type checks where necessary
  • Required widgets defined in system-defined type definitions (future iterations)

Author and Reviewer Checklist

Please verify the check list and ensure to tick them off before the MR is merged.

  • Provided a concise title for this Merge Request (MR)
  • Added a description to this MR explaining the reasons for the proposed change, per say why, not just what
    • Copy/paste the Slack conversation to document it for later, or upload screenshots. Verify that no confidential data is added, and the content is SAFE
  • Assign reviewers for this MR to the correct
    • The when to get approval handbook section explains when DRI approval is required
    • The who can approve handbook section explains how to identify the DRI
    • If the MR does not require DRI approval, consider asking someone on your team, such as your manager.
    • The approver may merge the MR. If they approve but don't merge, you can merge.
  • For transparency, share this MR with the audience that will be impacted.
    • Team: For changes that affect your direct team, share in your group Slack channel
    • Department: If the update affects your department, share the MR in your department Slack channel
    • Division: If the update affects your division, share the MR in your division Slack channel
    • Company: If the update affects all (or the majority of) GitLab team members, post an update in #whats-happening-at-gitlab linking to this MR

Commits

  • Adds configuration approach to work item types design doc

Merge request reports