1--- 2stage: none 3group: unassigned 4info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments 5comments: false 6description: Consolidating groups and projects 7--- 8 9# Consolidating Groups and Projects 10 11There are numerous features that exist exclusively within groups or 12projects. The boundary between group and project features used to be clear. 13However, there is growing demand to have group features within projects, and 14project features within groups. For example, having issues in groups, and epics 15in projects. 16 17The [Simplify Groups & Projects Working Group](https://about.gitlab.com/company/team/structure/working-groups/simplify-groups-and-projects/) 18determined that our architecture is a significant hurdle in sharing features 19across groups and projects. 20 21Architecture issue: <https://gitlab.com/gitlab-org/architecture/tasks/-/issues/7> 22 23## Challenges 24 25### Feature duplication 26 27When a feature needs to be made available on a different level, we have 28no established process in place. This results in the reimplementation of 29the same feature. Those implementations diverge from each other over time as 30they all live on their own. A few more problems with this approach: 31 32- Features are coupled to their container. In practice it is not straight 33 forward to decouple a feature from its container. The degree of coupling 34 varies across features. 35- Naive duplication of features will result in a more complex and fragile codebase. 36- Generalizing solutions across groups and projects may degrade system performance. 37- The range of features span across many teams, and these changes will need to 38 manage development interference. 39- The group/project hierarchy creates a natural feature hierarchy. When features 40 exist across containers the feature hierarchy becomes ambiguous. 41- Duplication of features slows down development velocity. 42 43There is potential for significant architectural changes. These changes will 44have to be independent of the product design, so that customer experience 45remains consistent. 46 47### Performance 48 49Resources can only be queried in elaborate / complicated ways. This caused 50performance issues with authorization, epics, and many other places. As an 51example, to query the projects a user has access to, the following sources need 52to be considered: 53 54- personal projects 55- direct group membership 56- direct project membership 57- inherited group membership 58- inherited project membership 59- group sharing 60- inherited membership via group sharing 61- project sharing 62 63Group / project membership, group / project sharing are also examples of 64duplicated features. 65 66## Goals 67 68For now this blueprint strictly relates to the engineering challenges. 69 70- Consolidate the group and project container architecture. 71- Develop a set of solutions to decouple features from their container. 72- Decouple engineering changes from product changes. 73- Develop a strategy to make architectural changes without adversely affecting 74 other teams. 75- Provide a solution for requests asking for features availability of other levels. 76 77## Proposal 78 79Use our existing `Namespace` model as a container for features. We already have 80a `Namespace` associated with `User` (personal namespace), and with `Group` 81(which is a subclass of `Namespace`). We can extend this further, by associating 82`Namespace` with `Projects` by introducing `ProjectNamespaces`. Each `Project` 83should be owned by its `ProjectNamespace`, and this relation should replace the 84existing `Project` <-> `Group` / personal namespace relation. 85 86We also lack a model specific for personal namespaces, and we use the generic 87`Namespace` model instead. This is confusing, but can be fixed by creating a 88dedicated subclass: `UserNamespace`. 89 90As a result, the `Namespace` hierarchy will transition to: 91 92```mermaid 93classDiagram 94 Namespace <|-- UserNamespace 95 Namespace <|-- Group 96 Namespace <|-- ProjectNamespace 97``` 98 99New features should be implemented on `Namespace`. Similarly, when a feature 100need to be reimplemented on a different level, moving it to `Namespace` 101essentially makes it available on all levels: 102 103- personal namespaces 104- groups 105- projects 106 107Various traversal queries are already available on `Namespaces` to query the 108group hierarchy. `Projects` represents the leaf nodes in the hierarchy, but with 109the introduction of `ProjectNamespace`, these traversal queries can be used to 110retrieve projects as well. 111 112This also enables further simplification of some of our core features: 113 114- routes should be generated based on the `Namespace` hierarchy, instead of 115 mixing project with the group hierarchy. 116- there is no need to differentiate between `GroupMembers` and `ProjectMembers`. 117 All `Members` should be related to a `Namespace`. This can lead to simplified 118 querying, and potentially deduplicating policies. 119 120As more and more features will be migrated to `Namespace`, the role of `Project` 121model will diminish over time to essentially a container around repository 122related functionality. 123 124## Iterations 125 126The work required to establish `Namespace` as a container for our features is 127tracked under [Consolidate Groups and Projects](https://gitlab.com/groups/gitlab-org/-/epics/6473) 128epic. 129 130## Migrating features to Namespaces 131 132The initial iteration will provide a framework to house features under `Namespaces`. Stage groups will eventually need to migrate their own features and functionality over to `Namespaces`. This may impact these features in unexpected ways. Therefore, to minimize UX debt and maintain product consistency, stage groups will have to consider a number of factors when migrating their features over to `Namespaces`: 133 1341. **Conceptual model**: What are the current and future state conceptual models of these features ([see object modeling for designers](https://hpadkisson.medium.com/object-modeling-for-designers-an-introduction-7871bdcf8baf))? These should be documented in Pajamas (example: [Merge Requests](https://design.gitlab.com/objects/merge-request)). 1351. **Merge conflicts**: What inconsistencies are there across project, group, and admin levels? How might these be addressed? For an example of how we rationalized this for labels, please see [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/338820). 1361. **Inheritance & information flow**: How is information inherited across our container hierarchy currently? How might this be impacted if complying with the new [inheritance behavior](https://gitlab.com/gitlab-org/gitlab/-/issues/343316) framework? 1371. **Settings**: Where can settings for this feature be found currently? How will these be impacted by `Namespaces`? 1381. **Access**: Who can access this feature and is that impacted by the new container structure? Are there any role or privacy considerations? 1391. **Tier**: Is there any tier functionality that is differentiated by projects and groups? 1401. **Documentation**: Is the structure and content of documentation impacted by these changes at all? 1411. **Solution proposal**: 142 - Think big: This analysis provides a great opportunity to zoom out and consider the feature UX as a whole. How could you make this feature lovable based on the new structure, inheritance, and capabilities afforded by `Namespaces`? Is there any UI which doesn't comply with Pajamas? 143 - Start small: What are the product changes that need to be made to assist with the migration? 144 - Move fast: Prioritise these solution ideas, document in issues, and create a roadmap for implementation. 145 146## Who 147 148Proposal: 149 150<!-- vale gitlab.Spelling = NO --> 151 152| Role | Who 153|------------------------------|-------------------------------------| 154| Author | Alex Pooley, Imre Farkas | 155| Architecture Evolution Coach | Dmitriy Zaporozhets, Grzegorz Bizon | 156| Engineering Leader | Michelle Gill | 157| Domain Expert | Jan Provaznik | 158 159<!-- vale gitlab.Spelling = YES --> 160 161DRIs: 162 163<!-- vale gitlab.Spelling = NO --> 164 165| Role | Who 166|------------------------------|------------------------| 167| Product | Melissa Ushakov | 168| Leadership | Michelle Gill | 169| Engineering | Imre Farkas | 170| Design | Nick Post | 171 172<!-- vale gitlab.Spelling = YES --> 173 174## Related topics 175 176- [Workspaces developer documentation](../../../development/workspaces/index.md) 177