Implement validation logic to ProjectStage

- Introducting StageEvents to define the available events
- Define the event pairing rules, since some events are not compatible
- Express default Cycle Analytics stages with the event structure

14 files changed, 440 insertions, 0 deletions

diff --git a/lib/gitlab/analytics/cycle_analytics/default_stages.rb b/lib/gitlab/analytics/cycle_analytics/default_stages.rb
new file mode 100644
index 00000000000..286c393005f
--- /dev/null
+++ b/lib/gitlab/analytics/cycle_analytics/default_stages.rb
@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+# This module represents the default Cycle Analytics stages that are currently provided by CE
+# Each method returns a hash that can be used to build a new stage object.
+#
+# Example:
+#
+# params = Gitlab::Analytics::CycleAnalytics::DefaultStages.params_for_issue_stage
+# Analytics::CycleAnalytics::ProjectStage.new(params)
+module Gitlab
+  module Analytics
+    module CycleAnalytics
+      module DefaultStages
+        def self.all
+          [
+            params_for_issue_stage,
+            params_for_plan_stage,
+            params_for_code_stage,
+            params_for_test_stage,
+            params_for_review_stage,
+            params_for_staging_stage,
+            params_for_production_stage
+          ]
+        end
+
+        def self.params_for_issue_stage
+          {
+            name: 'issue',
+            custom: false, # this stage won't be customizable, we provide it as it is
+            relative_position: 1, # when opening the CycleAnalytics page in CE, this stage will be the first item
+            start_event_identifier: :issue_created, # IssueCreated class is used as start event
+            end_event_identifier: :issue_stage_end # IssueStageEnd class is used as end event
+          }
+        end
+
+        def self.params_for_plan_stage
+          {
+            name: 'plan',
+            custom: false,
+            relative_position: 2,
+            start_event_identifier: :plan_stage_start,
+            end_event_identifier: :issue_first_mentioned_in_commit
+          }
+        end
+
+        def self.params_for_code_stage
+          {
+            name: 'code',
+            custom: false,
+            relative_position: 3,
+            start_event_identifier: :code_stage_start,
+            end_event_identifier: :merge_request_created
+          }
+        end
+
+        def self.params_for_test_stage
+          {
+            name: 'test',
+            custom: false,
+            relative_position: 4,
+            start_event_identifier: :merge_request_last_build_started,
+            end_event_identifier: :merge_request_last_build_finished
+          }
+        end
+
+        def self.params_for_review_stage
+          {
+            name: 'review',
+            custom: false,
+            relative_position: 5,
+            start_event_identifier: :merge_request_created,
+            end_event_identifier: :merge_request_merged
+          }
+        end
+
+        def self.params_for_staging_stage
+          {
+            name: 'staging',
+            custom: false,
+            relative_position: 6,
+            start_event_identifier: :merge_request_merged,
+            end_event_identifier: :merge_request_first_deployed_to_production
+          }
+        end
+
+        def self.params_for_production_stage
+          {
+            name: 'production',
+            custom: false,
+            relative_position: 7,
+            start_event_identifier: :merge_request_merged,
+            end_event_identifier: :merge_request_first_deployed_to_production
+          }
+        end
+      end
+    end
+  end
+end
diff --git a/lib/gitlab/analytics/cycle_analytics/stage_events.rb b/lib/gitlab/analytics/cycle_analytics/stage_events.rb
new file mode 100644
index 00000000000..d21f344f483
--- /dev/null
+++ b/lib/gitlab/analytics/cycle_analytics/stage_events.rb
@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module Gitlab
+  module Analytics
+    module CycleAnalytics
+      module StageEvents
+        # Convention:
+        # Issue: < 100
+        # MergeRequest: >= 100 && < 1000
+        # Custom events for default stages: >= 1000 (legacy)
+        ENUM_MAPPING = {
+          StageEvents::IssueCreated => 1,
+          StageEvents::IssueFirstMentionedInCommit => 2,
+          StageEvents::MergeRequestCreated => 100,
+          StageEvents::MergeRequestFirstDeployedToProduction => 101,
+          StageEvents::MergeRequestLastBuildFinished => 102,
+          StageEvents::MergeRequestLastBuildStarted => 103,
+          StageEvents::MergeRequestMerged => 104,
+          StageEvents::CodeStageStart => 1_000,
+          StageEvents::IssueStageEnd => 1_001,
+          StageEvents::PlanStageStart => 1_002
+        }.freeze
+
+        EVENTS = ENUM_MAPPING.keys.freeze
+
+        # Defines which start_event and end_event pairs are allowed
+        PAIRING_RULES = {
+          StageEvents::PlanStageStart => [
+            StageEvents::IssueFirstMentionedInCommit
+          ],
+          StageEvents::CodeStageStart => [
+            StageEvents::MergeRequestCreated
+          ],
+          StageEvents::IssueCreated => [
+            StageEvents::IssueStageEnd
+          ],
+          StageEvents::MergeRequestCreated => [
+            StageEvents::MergeRequestMerged
+          ],
+          StageEvents::MergeRequestLastBuildStarted => [
+            StageEvents::MergeRequestLastBuildFinished
+          ],
+          StageEvents::MergeRequestMerged => [
+            StageEvents::MergeRequestFirstDeployedToProduction
+          ]
+        }.freeze
+
+        def [](identifier)
+          events.find { |e| e.identifier.to_s.eql?(identifier.to_s) } || raise(KeyError)
+        end
+
+        # hash for defining ActiveRecord enum: identifier => number
+        def to_enum
+          ENUM_MAPPING.each_with_object({}) { |(k, v), hash| hash[k.identifier] = v }
+        end
+
+        # will be overridden in EE with custom events
+        def pairing_rules
+          PAIRING_RULES
+        end
+
+        # will be overridden in EE with custom events
+        def events
+          EVENTS
+        end
+
+        module_function :[], :to_enum, :pairing_rules, :events
+      end
+    end
+  end
+end
diff --git a/lib/gitlab/analytics/cycle_analytics/stage_events/code_stage_start.rb b/lib/gitlab/analytics/cycle_analytics/stage_events/code_stage_start.rb
new file mode 100644
index 00000000000..ff9c8a79225
--- /dev/null
+++ b/lib/gitlab/analytics/cycle_analytics/stage_events/code_stage_start.rb
@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Gitlab
+  module Analytics
+    module CycleAnalytics
+      module StageEvents
+        class CodeStageStart < SimpleStageEvent
+          def self.name
+            s_("CycleAnalyticsEvent|Issue first mentioned in a commit")
+          end
+
+          def self.identifier
+            :code_stage_start
+          end
+
+          def object_type
+            MergeRequest
+          end
+        end
+      end
+    end
+  end
+end
diff --git a/lib/gitlab/analytics/cycle_analytics/stage_events/issue_created.rb b/lib/gitlab/analytics/cycle_analytics/stage_events/issue_created.rb
new file mode 100644
index 00000000000..a601c9797f8
--- /dev/null
+++ b/lib/gitlab/analytics/cycle_analytics/stage_events/issue_created.rb
@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Gitlab
+  module Analytics
+    module CycleAnalytics
+      module StageEvents
+        class IssueCreated < SimpleStageEvent
+          def self.name
+            s_("CycleAnalyticsEvent|Issue created")
+          end
+
+          def self.identifier
+            :issue_created
+          end
+
+          def object_type
+            Issue
+          end
+        end
+      end
+    end
+  end
+end
diff --git a/lib/gitlab/analytics/cycle_analytics/stage_events/issue_first_mentioned_in_commit.rb b/lib/gitlab/analytics/cycle_analytics/stage_events/issue_first_mentioned_in_commit.rb
new file mode 100644
index 00000000000..7424043ef7b
--- /dev/null
+++ b/lib/gitlab/analytics/cycle_analytics/stage_events/issue_first_mentioned_in_commit.rb
@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Gitlab
+  module Analytics
+    module CycleAnalytics
+      module StageEvents
+        class IssueFirstMentionedInCommit < SimpleStageEvent
+          def self.name
+            s_("CycleAnalyticsEvent|Issue first mentioned in a commit")
+          end
+
+          def self.identifier
+            :issue_first_mentioned_in_commit
+          end
+
+          def object_type
+            Issue
+          end
+        end
+      end
+    end
+  end
+end
diff --git a/lib/gitlab/analytics/cycle_analytics/stage_events/issue_stage_end.rb b/lib/gitlab/analytics/cycle_analytics/stage_events/issue_stage_end.rb
new file mode 100644
index 00000000000..ceb229c552f
--- /dev/null
+++ b/lib/gitlab/analytics/cycle_analytics/stage_events/issue_stage_end.rb
@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Gitlab
+  module Analytics
+    module CycleAnalytics
+      module StageEvents
+        class IssueStageEnd < SimpleStageEvent
+          def self.name
+            PlanStageStart.name
+          end
+
+          def self.identifier
+            :issue_stage_end
+          end
+
+          def object_type
+            Issue
+          end
+        end
+      end
+    end
+  end
+end
diff --git a/lib/gitlab/analytics/cycle_analytics/stage_events/merge_request_created.rb b/lib/gitlab/analytics/cycle_analytics/stage_events/merge_request_created.rb
new file mode 100644
index 00000000000..8be00831b4f
--- /dev/null
+++ b/lib/gitlab/analytics/cycle_analytics/stage_events/merge_request_created.rb
@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Gitlab
+  module Analytics
+    module CycleAnalytics
+      module StageEvents
+        class MergeRequestCreated < SimpleStageEvent
+          def self.name
+            s_("CycleAnalyticsEvent|Merge request created")
+          end
+
+          def self.identifier
+            :merge_request_created
+          end
+
+          def object_type
+            MergeRequest
+          end
+        end
+      end
+    end
+  end
+end
diff --git a/lib/gitlab/analytics/cycle_analytics/stage_events/merge_request_first_deployed_to_production.rb b/lib/gitlab/analytics/cycle_analytics/stage_events/merge_request_first_deployed_to_production.rb
new file mode 100644
index 00000000000..6d7a2c023ff
--- /dev/null
+++ b/lib/gitlab/analytics/cycle_analytics/stage_events/merge_request_first_deployed_to_production.rb
@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Gitlab
+  module Analytics
+    module CycleAnalytics
+      module StageEvents
+        class MergeRequestFirstDeployedToProduction < SimpleStageEvent
+          def self.name
+            s_("CycleAnalyticsEvent|Merge request first deployed to production")
+          end
+
+          def self.identifier
+            :merge_request_first_deployed_to_production
+          end
+
+          def object_type
+            MergeRequest
+          end
+        end
+      end
+    end
+  end
+end
diff --git a/lib/gitlab/analytics/cycle_analytics/stage_events/merge_request_last_build_finished.rb b/lib/gitlab/analytics/cycle_analytics/stage_events/merge_request_last_build_finished.rb
new file mode 100644
index 00000000000..12d82fe2c62
--- /dev/null
+++ b/lib/gitlab/analytics/cycle_analytics/stage_events/merge_request_last_build_finished.rb
@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Gitlab
+  module Analytics
+    module CycleAnalytics
+      module StageEvents
+        class MergeRequestLastBuildFinished < SimpleStageEvent
+          def self.name
+            s_("CycleAnalyticsEvent|Merge request last build finish time")
+          end
+
+          def self.identifier
+            :merge_request_last_build_finished
+          end
+
+          def object_type
+            MergeRequest
+          end
+        end
+      end
+    end
+  end
+end
diff --git a/lib/gitlab/analytics/cycle_analytics/stage_events/merge_request_last_build_started.rb b/lib/gitlab/analytics/cycle_analytics/stage_events/merge_request_last_build_started.rb
new file mode 100644
index 00000000000..9e749b0fdfa
--- /dev/null
+++ b/lib/gitlab/analytics/cycle_analytics/stage_events/merge_request_last_build_started.rb
@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Gitlab
+  module Analytics
+    module CycleAnalytics
+      module StageEvents
+        class MergeRequestLastBuildStarted < SimpleStageEvent
+          def self.name
+            s_("CycleAnalyticsEvent|Merge request last build start time")
+          end
+
+          def self.identifier
+            :merge_request_last_build_started
+          end
+
+          def object_type
+            MergeRequest
+          end
+        end
+      end
+    end
+  end
+end
diff --git a/lib/gitlab/analytics/cycle_analytics/stage_events/merge_request_merged.rb b/lib/gitlab/analytics/cycle_analytics/stage_events/merge_request_merged.rb
new file mode 100644
index 00000000000..bbfb5d12992
--- /dev/null
+++ b/lib/gitlab/analytics/cycle_analytics/stage_events/merge_request_merged.rb
@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Gitlab
+  module Analytics
+    module CycleAnalytics
+      module StageEvents
+        class MergeRequestMerged < SimpleStageEvent
+          def self.name
+            s_("CycleAnalyticsEvent|Merge request merged")
+          end
+
+          def self.identifier
+            :merge_request_merged
+          end
+
+          def object_type
+            MergeRequest
+          end
+        end
+      end
+    end
+  end
+end
diff --git a/lib/gitlab/analytics/cycle_analytics/stage_events/plan_stage_start.rb b/lib/gitlab/analytics/cycle_analytics/stage_events/plan_stage_start.rb
new file mode 100644
index 00000000000..803317d8b55
--- /dev/null
+++ b/lib/gitlab/analytics/cycle_analytics/stage_events/plan_stage_start.rb
@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Gitlab
+  module Analytics
+    module CycleAnalytics
+      module StageEvents
+        class PlanStageStart < SimpleStageEvent
+          def self.name
+            s_("CycleAnalyticsEvent|Issue first associated with a milestone or issue first added to a board")
+          end
+
+          def self.identifier
+            :plan_stage_start
+          end
+
+          def object_type
+            Issue
+          end
+        end
+      end
+    end
+  end
+end
diff --git a/lib/gitlab/analytics/cycle_analytics/stage_events/simple_stage_event.rb b/lib/gitlab/analytics/cycle_analytics/stage_events/simple_stage_event.rb
new file mode 100644
index 00000000000..253c489d822
--- /dev/null
+++ b/lib/gitlab/analytics/cycle_analytics/stage_events/simple_stage_event.rb
@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Gitlab
+  module Analytics
+    module CycleAnalytics
+      module StageEvents
+        # Represents a simple event that usually refers to one database column and does not require additional user input
+        class SimpleStageEvent < StageEvent
+        end
+      end
+    end
+  end
+end
diff --git a/lib/gitlab/analytics/cycle_analytics/stage_events/stage_event.rb b/lib/gitlab/analytics/cycle_analytics/stage_events/stage_event.rb
new file mode 100644
index 00000000000..a55eee048c2
--- /dev/null
+++ b/lib/gitlab/analytics/cycle_analytics/stage_events/stage_event.rb
@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Gitlab
+  module Analytics
+    module CycleAnalytics
+      module StageEvents
+        # Base class for expressing an event that can be used for a stage.
+        class StageEvent
+          def initialize(params)
+            @params = params
+          end
+
+          def self.name
+            raise NotImplementedError
+          end
+
+          def self.identifier
+            raise NotImplementedError
+          end
+
+          def object_type
+            raise NotImplementedError
+          end
+        end
+      end
+    end
+  end
+end