State the default state of a feature flag in GraphQL docs

app/graphql/types/base_field.rb

@@ -95,7 +95,15 @@ module Types
     end
 
     def feature_documentation_message(key, description)
-      "#{description} Available only when feature flag `#{key}` is enabled."
+      message_parts = ["#{description} Available only when feature flag `#{key}` is enabled."]
+
+      message_parts << if Feature::Definition.has_definition?(key) && Feature::Definition.default_enabled?(key)
+                         "This flag is enabled by default."
+                       else
+                         "This flag is disabled by default, because the feature is experimental and is subject to change without notice."
+                       end
+
+      message_parts.join(' ')
     end
 
     def check_feature_flag(args)

doc/api/graphql/reference/index.md

@@ -294,7 +294,7 @@ Returns [`QueryComplexity`](#querycomplexity).
 
 ### `Query.runner`
 
-Find a runner. Available only when feature flag `runner_graphql_query` is enabled.
+Find a runner. Available only when feature flag `runner_graphql_query` is enabled. This flag is enabled by default.
 
 Returns [`CiRunner`](#cirunner).
 
@@ -331,7 +331,7 @@ Returns [`RunnerSetup`](#runnersetup).
 
 ### `Query.runners`
 
-Find runners visible to the current user. Available only when feature flag `runner_graphql_query` is enabled.
+Find runners visible to the current user. Available only when feature flag `runner_graphql_query` is enabled. This flag is enabled by default.
 
 Returns [`CiRunnerConnection`](#cirunnerconnection).
 
@@ -1121,7 +1121,7 @@ Input type: `CreateComplianceFrameworkInput`
 
 ### `Mutation.createCustomEmoji`
 
-Available only when feature flag `custom_emoji` is enabled.
+Available only when feature flag `custom_emoji` is enabled. This flag is disabled by default, because the feature is experimental and is subject to change without notice.
 
 Input type: `CreateCustomEmojiInput`
 
@@ -3618,7 +3618,7 @@ Input type: `RepositionImageDiffNoteInput`
 
 ### `Mutation.runnerDelete`
 
-Available only when feature flag `runner_graphql_query` is enabled.
+Available only when feature flag `runner_graphql_query` is enabled. This flag is enabled by default.
 
 Input type: `RunnerDeleteInput`
 
@@ -3638,7 +3638,7 @@ Input type: `RunnerDeleteInput`
 
 ### `Mutation.runnerUpdate`
 
-Available only when feature flag `runner_graphql_query` is enabled.
+Available only when feature flag `runner_graphql_query` is enabled. This flag is enabled by default.
 
 Input type: `RunnerUpdateInput`
 
@@ -3668,7 +3668,7 @@ Input type: `RunnerUpdateInput`
 
 ### `Mutation.runnersRegistrationTokenReset`
 
-Available only when feature flag `runner_graphql_query` is enabled.
+Available only when feature flag `runner_graphql_query` is enabled. This flag is enabled by default.
 
 Input type: `RunnersRegistrationTokenResetInput`
 
@@ -9266,7 +9266,7 @@ four standard [pagination arguments](#connection-pagination-arguments):
 | <a id="groupbillablememberscount"></a>`billableMembersCount` | [`Int`](#int) | The number of billable users in the group. |
 | <a id="groupcontainerrepositoriescount"></a>`containerRepositoriesCount` | [`Int!`](#int) | Number of container repositories in the group. |
 | <a id="groupcontainslockedprojects"></a>`containsLockedProjects` | [`Boolean!`](#boolean) | Includes at least one project where the repository size exceeds the limit. |
-| <a id="groupcustomemoji"></a>`customEmoji` | [`CustomEmojiConnection`](#customemojiconnection) | Custom emoji within this namespace. Available only when feature flag `custom_emoji` is enabled. (see [Connections](#connections)) |
+| <a id="groupcustomemoji"></a>`customEmoji` | [`CustomEmojiConnection`](#customemojiconnection) | Custom emoji within this namespace. Available only when feature flag `custom_emoji` is enabled. This flag is disabled by default, because the feature is experimental and is subject to change without notice. (see [Connections](#connections)) |
 | <a id="groupdescription"></a>`description` | [`String`](#string) | Description of the namespace. |
 | <a id="groupdescriptionhtml"></a>`descriptionHtml` | [`String`](#string) | The GitLab Flavored Markdown rendering of `description`. |
 | <a id="groupdora"></a>`dora` | [`Dora`](#dora) | The group's DORA metrics. |

spec/graphql/types/base_field_spec.rb

@@ -160,17 +160,17 @@ RSpec.describe Types::BaseField do
       let(:flag) { :test_flag }
 
       it 'prepends the description' do
-        expect(field.description). to eq 'Test description. Available only when feature flag `test_flag` is enabled.'
+        expect(field.description).to start_with 'Test description. Available only when feature flag `test_flag` is enabled.'
       end
 
       context 'falsey feature_flag values' do
         using RSpec::Parameterized::TableSyntax
 
-        where(:flag, :feature_value) do
-          ''  | false
-          ''  | true
-          nil | false
-          nil | true
+        where(:flag, :feature_value, :default_enabled) do
+          ''  | false | false
+          ''  | true  | false
+          nil | false | true
+          nil | true  | false
         end
 
         with_them do
@@ -179,6 +179,33 @@ RSpec.describe Types::BaseField do
           end
         end
       end
+
+      context 'with different default_enabled values' do
+        using RSpec::Parameterized::TableSyntax
+
+        where(:feature_value, :default_enabled, :expected_description) do
+          disabled_ff_description = "Test description. Available only when feature flag `test_flag` is enabled. This flag is disabled by default, because the feature is experimental and is subject to change without notice."
+          enabled_ff_description = "Test description. Available only when feature flag `test_flag` is enabled. This flag is enabled by default."
+
+          false | false | disabled_ff_description
+          true  | false | disabled_ff_description
+          false | true  | enabled_ff_description
+          true  | true  | enabled_ff_description
+        end
+
+        with_them do
+          before do
+            stub_feature_flags("#{flag}": feature_value)
+
+            allow(Feature::Definition).to receive(:has_definition?).with(flag).and_return(true)
+            allow(Feature::Definition).to receive(:default_enabled?).and_return(default_enabled)
+          end
+
+          it 'returns the correct availability in the description' do
+            expect(field.description). to eq expected_description
+          end
+        end
+      end
     end
   end
 
@@ -196,9 +223,8 @@ RSpec.describe Types::BaseField do
         feature_flag: 'foo_flag'
       )
 
-      expectation = 'Field description. Available only when feature flag `foo_flag` is enabled. Deprecated in 1.10: Deprecation reason.'
-
-      expect(field.description).to eq(expectation)
+      expect(field.description).to start_with('Field description. Available only when feature flag `foo_flag` is enabled.')
+      expect(field.description).to end_with('Deprecated in 1.10: Deprecation reason.')
     end
   end
 end