diff options
Diffstat (limited to 'doc/development/value_stream_analytics.md')
-rw-r--r-- | doc/development/value_stream_analytics.md | 20 |
1 files changed, 10 insertions, 10 deletions
diff --git a/doc/development/value_stream_analytics.md b/doc/development/value_stream_analytics.md index 4560a115562..b3692bd1d2c 100644 --- a/doc/development/value_stream_analytics.md +++ b/doc/development/value_stream_analytics.md @@ -1,7 +1,7 @@ --- stage: Manage group: Optimize -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +info: 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 --- # Value Stream Analytics development guide @@ -32,7 +32,7 @@ These events play a key role in the duration calculation. Formula: `duration = end_event_time - start_event_time` -To make the duration calculation flexible, each `Event` is implemented as a separate class. They're responsible for defining a timestamp expression that will be used in the calculation query. +To make the duration calculation flexible, each `Event` is implemented as a separate class. They're responsible for defining a timestamp expression that is used in the calculation query. #### Implementing an `Event` class @@ -41,12 +41,12 @@ There are a few methods that are required to be implemented, the `StageEvent` ba - `object_type` - `timestamp_projection` -The `object_type` method defines which domain object will be queried for the calculation. Currently two models are allowed: +The `object_type` method defines which domain object is queried for the calculation. Currently two models are allowed: - `Issue` - `MergeRequest` -For the duration calculation the `timestamp_projection` method will be used. +For the duration calculation the `timestamp_projection` method is used. ```ruby def timestamp_projection @@ -92,7 +92,7 @@ Some start/end event pairs are not "compatible" with each other. For example: The `StageEvents` module describes the allowed `start_event` and `end_event` pairings (`PAIRING_RULES` constant). If a new event is added, it needs to be registered in this module. βTo add a new event:β -1. Add an entry in `ENUM_MAPPING` with a unique number, it'll be used in the `Stage` model as `enum`. +1. Add an entry in `ENUM_MAPPING` with a unique number, which is used in the `Stage` model as `enum`. 1. Define which events are compatible with the event in the `PAIRING_RULES` hash. Supported start/end event pairings: @@ -185,19 +185,19 @@ Currently supported parents: 1. User navigates to the value stream analytics page. 1. User selects a group. 1. Backend loads the defined stages for the selected group. -1. Additions and modifications to the stages will be persisted within the selected group only. +1. Additions and modifications to the stages are persisted within the selected group only. ### Default stages The [original implementation](https://gitlab.com/gitlab-org/gitlab/-/issues/847) of value stream analytics defined 7 stages. These stages are always available for each parent, however altering these stages is not possible. β -To make things efficient and reduce the number of records created, the default stages are expressed as in-memory objects (not persisted). When the user creates a custom stage for the first time, all the stages will be persisted. This behavior is implemented in the value stream analytics service objects. +To make things efficient and reduce the number of records created, the default stages are expressed as in-memory objects (not persisted). When the user creates a custom stage for the first time, all the stages are persisted. This behavior is implemented in the value stream analytics service objects. β The reason for this was that we'd like to add the abilities to hide and order stages later on. ## Data Collector -`DataCollector` is the central point where the data will be queried from the database. The class always operates on a single stage and consists of the following components: +`DataCollector` is the central point where the data is queried from the database. The class always operates on a single stage and consists of the following components: - `BaseQueryBuilder`: - Responsible for composing the initial query. @@ -238,7 +238,7 @@ SELECT (START_EVENT_TIME-END_EVENT_TIME) as duration, END_EVENT.timestamp ## High-level overview - Rails Controller (`Analytics::CycleAnalytics` module): Value stream analytics exposes its data via JSON endpoints, implemented within the `analytics` workspace. Configuring the stages are also implements JSON endpoints (CRUD). -- Services (`Analytics::CycleAnalytics` module): All `Stage` related actions will be delegated to respective service objects. +- Services (`Analytics::CycleAnalytics` module): All `Stage` related actions are delegated to respective service objects. - Models (`Analytics::CycleAnalytics` module): Models are used to persist the `Stage` objects `ProjectStage` and `GroupStage`. - Feature classes (`Gitlab::Analytics::CycleAnalytics` module): - Responsible for composing queries and define feature specific business logic. @@ -248,7 +248,7 @@ SELECT (START_EVENT_TIME-END_EVENT_TIME) as duration, END_EVENT.timestamp Since we have a lots of events and possible pairings, testing each pairing is not possible. The rule is to have at least one test case using an `Event` class. -Writing a test case for a stage using a new `Event` can be challenging since data must be created for both events. To make this a bit simpler, each test case must be implemented in the `data_collector_spec.rb` where the stage is tested through the `DataCollector`. Each test case will be turned into multiple tests, covering the following cases: +Writing a test case for a stage using a new `Event` can be challenging since data must be created for both events. To make this a bit simpler, each test case must be implemented in the `data_collector_spec.rb` where the stage is tested through the `DataCollector`. Each test case is turned into multiple tests, covering the following cases: - Different parents: `Group` or `Project` - Different calculations: `Median`, `RecordsFetcher` or `DataForDurationChart` |