diff options
Diffstat (limited to 'lib/gitlab/config/README.md')
-rw-r--r-- | lib/gitlab/config/README.md | 29 |
1 files changed, 29 insertions, 0 deletions
diff --git a/lib/gitlab/config/README.md b/lib/gitlab/config/README.md new file mode 100644 index 00000000000..355dbdc8cfe --- /dev/null +++ b/lib/gitlab/config/README.md @@ -0,0 +1,29 @@ +# `::Gitlab::Config` module overview + +`::Gitlab::Config` is an abstract module used to build, traverse and translate +any kind of hierarchical, user-provided configuration. + +The most complex and widely used implementation is `::Gitlab::Ci::Config` +facade class. Please see `lib/gitlab/ci/config/README.md` for more information +around how it works. + +## High-level Overview + +The main motivation behind how `::Gitlab::Config` and `::Gitlab::Ci::Config` +work is to build an indirection layer between complex user-provided +configuration and GitLab itself. This helps us to extend configuration keywords +in a backwards-compatible way, and make sure that validation and transformation +rules are encapsulated within domain classes, what significantly helps to +reduce cognitive load on Engineers working on that part of the codebase. + +`Gitlab::Config` is a tool to work with hierarchical configuration: + +1. First we parse YAML with Ruby standard library `Psych`. +1. The resulting hash is being used to initialize a concrete implementation of `Gitlab::Config`. +1. In `::Gitlab::Ci::Config` abstract classes from `::Gitlab::Config` have their implementations. +1. Each domain class represents one or a group of hierarchical YAML entries, like `job:artifacts`. +1. Each entry knows what subentires are supported and how to validate them. +1. Upon loading a configuration we build an abstract syntax tree, and validate configuration. +1. If there are errors, the module can surface them to a user. +1. In case of config being valid, the config gets translated and augmented. +1. The result is a consistent representation that we can depend on in other parts of the codebase. |