Provide guidance to discourage use of shared and not_owned feature categories

Summary

We should provide clear guidance discouraging the use of shared and not_owned feature categories, as these create ownership gaps and make it difficult to properly triage and prioritize work.

Problem Statement

Currently, the codebase allows and documents the use of shared and not_owned feature categories:

  • :shared - Used for gems/code used across different product groups (e.g., rails)
  • :not_owned - Used for code that cannot be tied to a specific feature category (e.g., some admin sections, cross-cutting concerns)

However, according to our handbook guidance on shared responsibility issues:

Shared responsibility is no responsibility. When multiple teams share responsibility for an issue, it often means no team takes ownership, leading to the issue being deprioritized or ignored.

The use of shared and not_owned feature categories creates exactly this problem:

  1. Lack of clear ownership - No single team is responsible for maintenance, bug fixes, or improvements
  2. Difficulty in triage - Issues cannot be properly routed to the right team
  3. Accumulation of technical debt - Code without clear owners tends to accumulate problems over time
  4. Support escalation confusion - Support tickets get shuffled between teams (as noted in #577893 (closed))
  5. Code review challenges - Reviewer Roulette cannot assign appropriate reviewers

Current State

From the feature categorization documentation:

Shared category usage: 

# For gems that are used across different product groups we use
# feature_category: :shared. For example, `rails` is used through out the
# application and it's shared with multiple groups.

Not_owned category usage: 

class SomeCrossCuttingConcernWorker
  include ApplicationWorker

  # Declares that this worker does not map to a feature category
  feature_category :not_owned # rubocop:disable Gitlab/AvoidFeatureCategoryNotOwned
end

Note that :not_owned already requires a RuboCop disable comment, suggesting we recognize this as problematic.

Proposal

We should update our documentation to:

  1. Explicitly discourage the use of shared and not_owned feature categories
  2. Provide guidance on how to assign proper ownership instead:
    • For cross-cutting concerns: Assign to the team that uses it most frequently or would be most impacted by issues
    • For shared infrastructure: Assign to the team responsible for the underlying platform (e.g., Database, Scalability)
    • For admin functionality: Assign based on the specific feature area (e.g., admin user management → Authentication & Authorization)
  3. Document the process for determining ownership when it's unclear
  4. Create a migration plan for existing shared and not_owned code to be assigned to specific teams

Recommended approach for unclear ownership:

When ownership is unclear, follow this decision tree:

  1. Search existing usages, Controllers, API endpoints have feature_category. The bounded context (config/bounded_contexts.yml) will also have related feature_categories.
  2. Which team would be most impacted if this broke? → Assign to that team
  3. Which team has the most domain expertise? → Assign to that team
  4. Which team touches this code most frequently? → Assign to that team
  5. Is this truly cross-cutting? → Assign to the platform/infrastructure team that owns the underlying layer

Benefits

  • Improved accountability - Every piece of code has a clear owner
  • Better triage - Issues can be properly routed and prioritized
  • Reduced technical debt - Owned code gets maintained, e.g. #547252
  • Clearer escalation paths - Support knows who to contact
  • Better code review - Appropriate domain experts are assigned

Related Issues

  • #577893 (closed) - Post-Reorganization Cleanup and Ownership Mapping (identified "Shared" or "not owned" categories as causing responsibility gaps)
  • #216110 (closed) - DRI for "not_owned" category (attempted to find ownership for not_owned items)

Documentation to Update

Acceptance Criteria

  • Documentation clearly states that shared and not_owned should be avoided
  • Guidance is provided on how to determine proper ownership
  • Process is documented for migrating existing shared/not_owned code
  • Examples are updated to show proper ownership assignment

References

Edited by 🤖 GitLab Bot 🤖