<!--IssueSummary start--> <details> <summary> Everyone can contribute. [Help move this issue forward](https://handbook.gitlab.com/handbook/marketing/developer-relations/contributor-success/community-contributors-workflows/#contributor-links) while earning points, leveling up and collecting rewards. </summary> - [Work on this issue](https://contributors.gitlab.com/manage-issue?action=work&projectId=278964&issueIid=581839) - [Close this issue](https://contributors.gitlab.com/manage-issue?action=close&projectId=278964&issueIid=581839) </details> <!--IssueSummary end--> Original issue https://gitlab.com/gitlab-org/gitlab/-/issues/581839 ## 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](https://handbook.gitlab.com/handbook/product-development/how-we-work/issue-triage/#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 gitlab#577893) 5. **Code review challenges** - Reviewer Roulette cannot assign appropriate reviewers ## Current State From the [feature categorization documentation](https://docs.gitlab.com/development/feature_categorization/): ### Shared category usage: ```ruby # 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: ```ruby 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 (Rails and below, not cross-cutting code): Assign to the team responsible for the underlying platform (e.g., Database, :rails_platform) - 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`. Specs will also have `feature_category` 1. **Which team would be most impacted if this broke?** → Assign to that team 2. **Which team has the most domain expertise?** → Assign to that team 3. **Which team touches this code most frequently?** → Assign to that team 4. **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. https://gitlab.com/gitlab-org/gitlab/-/issues/547252 - **Clearer escalation paths** - Support knows who to contact - **Better code review** - Appropriate domain experts are assigned ## Related Issues - gitlab#577893 - Post-Reorganization Cleanup and Ownership Mapping (identified "Shared" or "not owned" categories as causing responsibility gaps) - gitlab#216110 - DRI for "not_owned" category (attempted to find ownership for not_owned items) ## Documentation to Update - [ ] [Feature Categorization documentation](https://docs.gitlab.com/development/feature_categorization/) - Add section discouraging `shared` and `not_owned`, especially in https://docs.gitlab.com/development/feature_categorization/#shared-feature-category. - [ ] [Feature Categorization documentation](https://docs.gitlab.com/development/feature_categorization/) - Add decision tree for determining ownership - [ ] [RSpec feature category guidelines](https://docs.gitlab.com/development/feature_categorization/#rspec-examples) - Strengthen guidance against these categories ## 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 - [Handbook: Shared Responsibility Issues](https://handbook.gitlab.com/handbook/product-development/how-we-work/issue-triage/#shared-responsibility-issues) - [Development Docs: Feature Categorization](https://docs.gitlab.com/development/feature_categorization/) - [Product Categories](https://handbook.gitlab.com/handbook/product/categories/)