Merge branch '328815-document-values-of-mergerequest-mergestatus' into 'master'

Resolve "Document values of `MergeRequest.mergeStatus`"

See merge request gitlab-org/gitlab!62729

app/graphql/types/merge_request_type.rb

@@ -82,7 +82,11 @@ module Types
     field :force_remove_source_branch, GraphQL::BOOLEAN_TYPE, method: :force_remove_source_branch?, null: true,
           description: 'Indicates if the project settings will lead to source branch deletion after merge.'
     field :merge_status, GraphQL::STRING_TYPE, method: :public_merge_status, null: true,
-          description: 'Status of the merge request.'
+          description: 'Status of the merge request.',
+          deprecated: { reason: :renamed, replacement: 'MergeRequest.mergeStatusEnum', milestone: '14.0' }
+    field :merge_status_enum, ::Types::MergeRequests::MergeStatusEnum,
+          method: :public_merge_status, null: true,
+          description: 'Merge status of the merge request.'
     field :in_progress_merge_commit_sha, GraphQL::STRING_TYPE, null: true,
           description: 'Commit SHA of the merge request if merge is in progress.'
     field :merge_error, GraphQL::STRING_TYPE, null: true,

app/graphql/types/merge_requests/merge_status_enum.rb

+# frozen_string_literal: true
+
+module Types
+  module MergeRequests
+    class MergeStatusEnum < BaseEnum
+      graphql_name 'MergeStatus'
+      description 'Representation of whether a GitLab merge request can be merged.'
+
+      value 'UNCHECKED',
+            value: 'unchecked',
+            description: 'Merge status has not been checked.'
+      value 'CHECKING',
+            value: 'checking',
+            description: 'Currently checking for mergeability.'
+      value 'CAN_BE_MERGED',
+            value: 'can_be_merged',
+            description: 'There are no conflicts between the source and target branches.'
+      value 'CANNOT_BE_MERGED',
+            value: 'cannot_be_merged',
+            description: 'There are conflicts between the source and target branches.'
+      value 'CANNOT_BE_MERGED_RECHECK',
+            value: 'cannot_be_merged_recheck',
+            description: 'Currently unchecked. The previous state was `CANNOT_BE_MERGED`.'
+    end
+  end
+end

doc/api/graphql/reference/index.md

@@ -9992,7 +9992,8 @@ Maven metadata.
 | <a id="mergerequestmergecommitsha"></a>`mergeCommitSha` | [`String`](#string) | SHA of the merge request commit (set once merged). |
 | <a id="mergerequestmergeerror"></a>`mergeError` | [`String`](#string) | Error message due to a merge error. |
 | <a id="mergerequestmergeongoing"></a>`mergeOngoing` | [`Boolean!`](#boolean) | Indicates if a merge is currently occurring. |
-| <a id="mergerequestmergestatus"></a>`mergeStatus` | [`String`](#string) | Status of the merge request. |
+| <a id="mergerequestmergestatus"></a>`mergeStatus` **{warning-solid}** | [`String`](#string) | **Deprecated** in 14.0. This was renamed. Use: [`MergeRequest.mergeStatusEnum`](#mergerequestmergestatusenum). |
+| <a id="mergerequestmergestatusenum"></a>`mergeStatusEnum` | [`MergeStatus`](#mergestatus) | Merge status of the merge request. |
 | <a id="mergerequestmergetrainscount"></a>`mergeTrainsCount` | [`Int`](#int) | Number of merge requests in the merge train. |
 | <a id="mergerequestmergeuser"></a>`mergeUser` | [`UserCore`](#usercore) | User who merged this merge request. |
 | <a id="mergerequestmergewhenpipelinesucceeds"></a>`mergeWhenPipelineSucceeds` | [`Boolean`](#boolean) | Indicates if the merge has been set to be merged when its pipeline succeeds (MWPS). |
@@ -14425,6 +14426,18 @@ State of a GitLab merge request.
 | <a id="mergerequeststatemerged"></a>`merged` | Merge request has been merged. |
 | <a id="mergerequeststateopened"></a>`opened` | In open state. |
 
+### `MergeStatus`
+
+Representation of whether a GitLab merge request can be merged.
+
+| Value | Description |
+| ----- | ----------- |
+| <a id="mergestatuscannot_be_merged"></a>`CANNOT_BE_MERGED` | There are conflicts between the source and target branches. |
+| <a id="mergestatuscannot_be_merged_recheck"></a>`CANNOT_BE_MERGED_RECHECK` | Currently unchecked. The previous state was `CANNOT_BE_MERGED`. |
+| <a id="mergestatuscan_be_merged"></a>`CAN_BE_MERGED` | There are no conflicts between the source and target branches. |
+| <a id="mergestatuschecking"></a>`CHECKING` | Currently checking for mergeability. |
+| <a id="mergestatusunchecked"></a>`UNCHECKED` | Merge status has not been checked. |
+
 ### `MergeStrategyEnum`
 
 | Value | Description |

doc/api/merge_requests.md

@@ -405,6 +405,16 @@ Parameters:
 ]
 ```
 
+The `merge_status` field may hold one of the following values:
+
+| Value                      | Interpretation                                                        |
+|----------------------------|-----------------------------------------------------------------------|
+| `unchecked`                | We have not checked this yet                                          |
+| `checking`                 | We are currently checking if the merge request can be merged          |
+| `can_be_merged`            | This merge request can be merged without conflict                     |
+| `cannot_be_merged`         | There are merge conflicts between the source and target branches      |
+| `cannot_be_merged_recheck` | Currently unchecked. Before the current changes, there were conflicts |
+
 Users on GitLab Premium or higher also see
 the `approvals_before_merge` parameter:
 

spec/graphql/types/merge_request_type_spec.rb

@@ -3,6 +3,8 @@
 require 'spec_helper'
 
 RSpec.describe GitlabSchema.types['MergeRequest'] do
+  include GraphqlHelpers
+
   specify { expect(described_class).to expose_permissions_using(Types::PermissionTypes::MergeRequest) }
 
   specify { expect(described_class).to require_graphql_authorizations(:read_merge_request) }
@@ -19,7 +21,9 @@ RSpec.describe GitlabSchema.types['MergeRequest'] do
       target_branch work_in_progress draft merge_when_pipeline_succeeds diff_head_sha
       merge_commit_sha user_notes_count user_discussions_count should_remove_source_branch
       diff_refs diff_stats diff_stats_summary
-      force_remove_source_branch merge_status in_progress_merge_commit_sha
+      force_remove_source_branch
+      merge_status merge_status_enum
+      in_progress_merge_commit_sha
       merge_error allow_collaboration should_be_rebased rebase_commit_sha
       rebase_in_progress default_merge_commit_message
       merge_ongoing mergeable_discussions_state web_url
@@ -106,4 +110,27 @@ RSpec.describe GitlabSchema.types['MergeRequest'] do
       execute_query
     end
   end
+
+  describe 'merge_status_enum' do
+    let(:type) { GitlabSchema.types['MergeStatus'] }
+
+    it 'has the type MergeStatus' do
+      expect(described_class.fields['mergeStatusEnum']).to have_graphql_type(type)
+    end
+
+    let_it_be(:project) { create(:project, :public) }
+
+    %i[preparing unchecked cannot_be_merged_recheck checking cannot_be_merged_rechecking can_be_merged cannot_be_merged].each do |state|
+      context "when the the DB value is #{state}" do
+        let(:merge_request) { create(:merge_request, :unique_branches, source_project: project, merge_status: state.to_s) }
+
+        it 'serializes correctly' do
+          value = resolve_field(:merge_status_enum, merge_request)
+          value = type.coerce_isolated_result(value)
+
+          expect(value).to eq(merge_request.public_merge_status.upcase)
+        end
+      end
+    end
+  end
 end