Improve error messages when adding a child epic

- return specific error messages when
adding a single child epic which fails
- keep (mostly) general errors when
adding more child epics at once

changelogs/unreleased/35546-child-epic-error-messages.yml

+---
+title: Improve error messages when adding a child epic
+merge_request: 22688
+author:
+type: fixed

ee/app/models/ee/epic.rb

@@ -325,24 +325,32 @@ module EE
     def update_project_counter_caches
     end
 
-    # we call this when creating a new epic (Epics::CreateService) or linking an existing one (EpicLinks::CreateService)
-    # when called from EpicLinks::CreateService we pass
-    #   parent_epic - because we don't have parent attribute set on epic
-    #   parent_group_descendants - we have preloaded them in the service and we want to prevent performance problems
-    #     when linking a lot of issues
     def valid_parent?(parent_epic: nil, parent_group_descendants: nil)
       parent_epic ||= parent
 
       return true unless parent_epic
 
-      parent_group_descendants ||= parent_epic.group.self_and_descendants
+      validate_parent(parent_epic, parent_group_descendants)
+
+      errors.empty?
+    end
 
-      return false if self == parent_epic
-      return false if level_depth_exceeded?(parent_epic)
-      return false if parent_epic.has_ancestor?(self)
-      return false if parent_epic.children.to_a.include?(self)
+    def validate_parent(parent_epic = parent, parent_group_descendents = nil)
+      return unless parent_epic
+
+      parent_group_descendants ||= parent_epic.group.self_and_descendants
 
-      parent_group_descendants.include?(group)
+      if self == parent_epic
+        errors.add :parent, 'Cannot add an epic as a child of itself'
+      elsif parent_epic.children.to_a.include?(self)
+        errors.add :parent, "This epic can't be added as it is already assigned to the parent"
+      elsif parent_epic.has_ancestor?(self)
+        errors.add :parent, "This epic can't be added as it is already assigned to this epic's ancestor"
+      elsif !parent_group_descendants.include?(group)
+        errors.add :parent, "This epic can't be added because parent and child epics must belong to the same group"
+      elsif level_depth_exceeded?(parent_epic)
+        errors.add :parent, "This epic can't be added as the maximum depth of nested epics would be exceeded"
+      end
     end
 
     def issues_readable_by(current_user, preload: nil)
@@ -363,13 +371,6 @@ module EE
       super.merge(label_url_method: :group_epics_url)
     end
 
-    def validate_parent
-      return true if valid_parent?
-
-      errors.add :parent, 'The parent is not valid'
-    end
-    private :validate_parent
-
     def level_depth_exceeded?(parent_epic)
       hierarchy.max_descendants_depth.to_i + parent_epic.base_and_ancestors.count >= MAX_HIERARCHY_DEPTH
     end

ee/app/services/epic_links/create_service.rb

@@ -4,14 +4,31 @@ module EpicLinks
   class CreateService < IssuableLinks::CreateService
     def execute
       if issuable.max_hierarchy_depth_achieved?
-        return error('Epic hierarchy level too deep', 409)
+        return error("This epic can't be added because the parent is already at the maximum depth from its most distant ancestor", 409)
       end
 
-      super
+      if referenced_issuables.count == 1
+        create_single_link
+      else
+        super
+      end
     end
 
     private
 
+    def create_single_link
+      child_epic = referenced_issuables.first
+
+      if linkable_epic?(child_epic)
+        set_child_epic!(child_epic)
+
+        create_notes(child_epic, nil)
+        success
+      else
+        error(child_epic.errors.messages[:parent].first, 409)
+      end
+    end
+
     def affected_epics(epics)
       [issuable, epics].flatten.uniq
     end