diff options
Diffstat (limited to 'doc/development/directory_structure.md')
| -rw-r--r-- | doc/development/directory_structure.md | 97 |
1 files changed, 7 insertions, 90 deletions
diff --git a/doc/development/directory_structure.md b/doc/development/directory_structure.md index 27384fa559f..34ee86d9ee5 100644 --- a/doc/development/directory_structure.md +++ b/doc/development/directory_structure.md @@ -1,94 +1,11 @@ --- -stage: none -group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +redirect_to: 'software_design.md' +remove_date: '2023-01-24' --- -# Backend directory structure +This document was moved to [another location](software_design.md) -## Use namespaces to define bounded contexts - -A healthy application is divided into macro and sub components that represent the contexts at play, -whether they are related to business domain or infrastructure code. - -As GitLab code has so many features and components it's hard to see what contexts are involved. -We should expect any class to be defined inside a module/namespace that represents the contexts where it operates. - -When we namespace classes inside their domain: - -- Similar terminology becomes unambiguous as the domain clarifies the meaning: - For example, `MergeRequests::Diff` and `Notes::Diff`. -- Top-level namespaces could be associated to one or more groups identified as domain experts. -- We can better identify the interactions and coupling between components. - For example, several classes inside `MergeRequests::` domain interact more with `Ci::` - domain and less with `ImportExport::`. - -```ruby -# bad -class MyClass -end - -# good -module MyDomain - class MyClass - end -end -``` - -### About namespace naming - -A good guideline for naming a top-level namespace (bounded context) is to use the related -[feature category](https://gitlab.com/gitlab-com/www-gitlab-com/-/blob/master/data/categories.yml). For example, `Continuous Integration` feature category maps to `Ci::` namespace. - -Alternatively a new class could be added to `Projects::` or `Groups::` if it's either: - -- Strictly related to one of these domains. For example `Projects::Alias`. -- A new component that does not have yet a more specific domain. In this case, when - a more explicit domain does emerge we would need to move the class to a more specific - namespace. - -Do not use the [stage or group name](https://about.gitlab.com/handbook/product/categories/#devops-stages) -since a feature category could be reassigned to a different group in the future. - -```ruby -# bad -module Create - class Commit - end -end - -# good -module Repositories - class Commit - end -end -``` - -On the other hand, a feature category may sometimes be too granular. Features tend to be -treated differently according to Product and Marketing, while they may share a lot of -domain models and behavior under the hood. In this case, having too many bounded contexts -could make them shallow and more coupled with other contexts. - -Bounded contexts (or top-level namespaces) can be seen as macro-components in the overall app. -Good bounded contexts should be [deep](https://medium.com/@nakabonne/depth-of-module-f62dac3c2fdb) -so consider having nested namespaces to further break down complex parts of the domain. -For example, `Ci::Config::`. - -For example, instead of having separate and granular bounded contexts like: `ContainerScanning::`, -`ContainerHostSecurity::`, `ContainerNetworkSecurity::`, we could have: - -```ruby -module ContainerSecurity - module HostSecurity - end - - module NetworkSecurity - end - - module Scanning - end -end -``` - -If classes that are defined into a namespace have a lot in common with classes in other namespaces, -chances are that these two namespaces are part of the same bounded context. +<!-- This redirect file can be deleted after <2023-01-24>. --> +<!-- Redirects that point to other docs in the same project expire in three months. --> +<!-- Redirects that point to docs in a different project or site (link is not relative and starts with `https:`) expire in one year. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> |