summaryrefslogtreecommitdiff
path: root/doc/development/directory_structure.md
diff options
context:
space:
mode:
authorGitLab Bot <gitlab-bot@gitlab.com>2021-03-16 18:18:33 +0000
committerGitLab Bot <gitlab-bot@gitlab.com>2021-03-16 18:18:33 +0000
commitf64a639bcfa1fc2bc89ca7db268f594306edfd7c (patch)
treea2c3c2ebcc3b45e596949db485d6ed18ffaacfa1 /doc/development/directory_structure.md
parentbfbc3e0d6583ea1a91f627528bedc3d65ba4b10f (diff)
downloadgitlab-ce-f64a639bcfa1fc2bc89ca7db268f594306edfd7c.tar.gz
Add latest changes from gitlab-org/gitlab@13-10-stable-eev13.10.0-rc40
Diffstat (limited to 'doc/development/directory_structure.md')
-rw-r--r--doc/development/directory_structure.md58
1 files changed, 58 insertions, 0 deletions
diff --git a/doc/development/directory_structure.md b/doc/development/directory_structure.md
index c2329feb941..c96e2cc3254 100644
--- a/doc/development/directory_structure.md
+++ b/doc/development/directory_structure.md
@@ -34,3 +34,61 @@ module MyDomain
end
end
```
+
+### About namespace naming
+
+A good guideline for naming a top-level namespace (bounded context) is to use the related
+feature category. 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.
+E.g. `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.