Merge branch 'docs-service-object' into 'master'

Development guideline Docs: Not everything is a service object

See merge request gitlab-org/gitlab!71343

app/services/base_service.rb

@@ -6,13 +6,7 @@
 # and existing service will use these one by one.
 # After all are migrated, we can remove this class.
 #
-# New services should consider inheriting from:
-#
-# - BaseContainerService for services scoped by container (project or group)
-# - BaseProjectService for services scoped to projects
-# - BaseGroupService for services scoped to groups
-#
-# or, create a new base class and update this comment.
+# For new services, please see https://docs.gitlab.com/ee/development/reusing_abstractions.html#service-classes
 class BaseService
   include BaseServiceUtility
   include Gitlab::Experiment::Dsl

doc/development/reusing_abstractions.md

@@ -133,8 +133,20 @@ Everything in `lib/api`.
 
 Everything that resides in `app/services`.
 
+Services should consider inheriting from:
+
+- `BaseContainerService` for services scoped by container (project or group)
+- `BaseProjectService` for services scoped to projects
+- `BaseGroupService` for services scoped to groups
+
+or, create a new base class and update the list above.
+
+Legacy classes inherited from `BaseService` for historical reasons.
+
 In Service classes the use of `execute` and `#execute` is preferred over `call` and `#call`.
 
+Classes that are not service objects should be [created elsewhere](directory_structure.md#use-namespaces-to-define-bounded-contexts, such as in `lib`.
+
 #### ServiceResponse
 
 Service classes usually have an `execute` method, which can return a