From 5097ced579dcea3e4b43d9843aba3d28766aea00 Mon Sep 17 00:00:00 2001
From: Luke Duncalfe <lduncalfe@gitlab.com>
Date: Tue, 2 Aug 2022 01:15:43 +0000
Subject: [PATCH] GraphQL docs: Show descriptions for `:alpha` items
Previously the original descriptions were not displayed for "inline"
docs. This was because marking items as "alpha" leverages the our
deprecations, and for deprecated item we only display the deprecation
notice and not the original item description.
For alpha fields, we now display the warning of its instability, but do
also display the original description too.
Changelog: added
---
doc/api/graphql/reference/index.md | 4 +-
lib/gitlab/graphql/deprecation.rb | 6 +-
spec/lib/gitlab/graphql/deprecation_spec.rb | 16 +++
spec/tooling/graphql/docs/renderer_spec.rb | 122 ++++++++++++++++++++
tooling/graphql/docs/helper.rb | 5 +-
5 files changed, 149 insertions(+), 4 deletions(-)
diff --git a/doc/api/graphql/reference/index.md b/doc/api/graphql/reference/index.md
index 4c237c99a3994..aed5d0a837e87 100644
--- a/doc/api/graphql/reference/index.md
+++ b/doc/api/graphql/reference/index.md
@@ -10244,7 +10244,7 @@ CI/CD variables for a project.
| <a id="cirunnershortsha"></a>`shortSha` | [`String`](#string) | First eight characters of the runner's token used to authenticate new job requests. Used as the runner's unique ID. |
| <a id="cirunnertaglist"></a>`tagList` | [`[String!]`](#string) | Tags associated with the runner. |
| <a id="cirunnertokenexpiresat"></a>`tokenExpiresAt` | [`Time`](#time) | Runner token expiration time. |
-| <a id="cirunnerupgradestatus"></a>`upgradeStatus` **{warning-solid}** | [`CiRunnerUpgradeStatus`](#cirunnerupgradestatus) | **Introduced** in 14.10. This feature is in Alpha. It can be changed or removed at any time. |
+| <a id="cirunnerupgradestatus"></a>`upgradeStatus` **{warning-solid}** | [`CiRunnerUpgradeStatus`](#cirunnerupgradestatus) | **Introduced** in 14.10. This feature is in Alpha. It can be changed or removed at any time. Availability of upgrades for the runner. |
| <a id="cirunneruserpermissions"></a>`userPermissions` | [`RunnerPermissions!`](#runnerpermissions) | Permissions for the current user on the resource. |
| <a id="cirunnerversion"></a>`version` | [`String`](#string) | Version of the runner. |
@@ -19732,7 +19732,7 @@ Issue type.
| <a id="issuetypeincident"></a>`INCIDENT` | Incident issue type. |
| <a id="issuetypeissue"></a>`ISSUE` | Issue issue type. |
| <a id="issuetyperequirement"></a>`REQUIREMENT` | Requirement issue type. |
-| <a id="issuetypetask"></a>`TASK` **{warning-solid}** | **Introduced** in 15.2. This feature is in Alpha. It can be changed or removed at any time. |
+| <a id="issuetypetask"></a>`TASK` **{warning-solid}** | **Introduced** in 15.2. This feature is in Alpha. It can be changed or removed at any time. Task issue type. Available only when feature flag `work_items` is enabled. |
| <a id="issuetypetest_case"></a>`TEST_CASE` | Test Case issue type. |
### `IterationSearchableField`
diff --git a/lib/gitlab/graphql/deprecation.rb b/lib/gitlab/graphql/deprecation.rb
index 7ba339d4191d0..9b17962f9ec93 100644
--- a/lib/gitlab/graphql/deprecation.rb
+++ b/lib/gitlab/graphql/deprecation.rb
@@ -94,6 +94,10 @@ def deprecation_reason
].compact.join(' ')
end
+ def alpha?
+ reason == REASON_ALPHA
+ end
+
private
attr_reader :reason, :milestone, :replacement
@@ -127,7 +131,7 @@ def description_suffix
# Retruns 'Introduced in <milestone>' for :alpha deprecations.
# Formatted to markdown or plain format.
def changed_in_milestone(format: :plain)
- verb = if reason == REASON_ALPHA
+ verb = if alpha?
'Introduced'
else
'Deprecated'
diff --git a/spec/lib/gitlab/graphql/deprecation_spec.rb b/spec/lib/gitlab/graphql/deprecation_spec.rb
index 0ff4c232c6f3d..c9b4721919850 100644
--- a/spec/lib/gitlab/graphql/deprecation_spec.rb
+++ b/spec/lib/gitlab/graphql/deprecation_spec.rb
@@ -237,4 +237,20 @@
end
end
end
+
+ describe '#alpha?' do
+ let(:options) { { milestone: '10.10', reason: reason } }
+
+ context 'when `reason` is `:alpha`' do
+ let(:reason) { described_class::REASON_ALPHA }
+
+ it { is_expected.to be_alpha }
+ end
+
+ context 'when `reason` is not `:alpha`' do
+ let(:reason) { described_class::REASON_RENAMED }
+
+ it { is_expected.not_to be_alpha }
+ end
+ end
end
diff --git a/spec/tooling/graphql/docs/renderer_spec.rb b/spec/tooling/graphql/docs/renderer_spec.rb
index 18256fea2d63b..bf2383507aac0 100644
--- a/spec/tooling/graphql/docs/renderer_spec.rb
+++ b/spec/tooling/graphql/docs/renderer_spec.rb
@@ -347,6 +347,128 @@ def resolve_type(obj, ctx)
it_behaves_like 'renders correctly as GraphQL documentation'
end
+ context 'when an argument is in alpha' do
+ let(:type) do
+ Class.new(Types::BaseObject) do
+ graphql_name 'AlphaTest'
+ description 'A thing with arguments in alpha'
+
+ field :foo,
+ type: GraphQL::Types::String,
+ null: false,
+ description: 'A description.' do
+ argument :foo_arg, GraphQL::Types::String,
+ required: false,
+ description: 'Argument description.',
+ alpha: { milestone: '101.2' }
+ end
+ end
+ end
+
+ let(:section) do
+ <<~DOC
+ ##### `AlphaTest.foo`
+
+ A description.
+
+ Returns [`String!`](#string).
+
+ ###### Arguments
+
+ | Name | Type | Description |
+ | ---- | ---- | ----------- |
+ | <a id="alphatestfoofooarg"></a>`fooArg` **{warning-solid}** | [`String`](#string) | **Introduced** in 101.2. This feature is in Alpha. It can be changed or removed at any time. Argument description. |
+ DOC
+ end
+
+ it_behaves_like 'renders correctly as GraphQL documentation'
+ end
+
+ context 'when a field is in alpha' do
+ let(:type) do
+ Class.new(Types::BaseObject) do
+ graphql_name 'AlphaTest'
+ description 'A thing with fields in alpha'
+
+ field :foo,
+ type: GraphQL::Types::String,
+ null: false,
+ alpha: { milestone: '1.10' },
+ description: 'A description.'
+ field :foo_with_args,
+ type: GraphQL::Types::String,
+ null: false,
+ alpha: { milestone: '1.10' },
+ description: 'A description.' do
+ argument :arg, GraphQL::Types::Int, required: false, description: 'Argity'
+ end
+ end
+ end
+
+ let(:section) do
+ <<~DOC
+ ### `AlphaTest`
+
+ A thing with fields in alpha.
+
+ #### Fields
+
+ | Name | Type | Description |
+ | ---- | ---- | ----------- |
+ | <a id="alphatestfoo"></a>`foo` **{warning-solid}** | [`String!`](#string) | **Introduced** in 1.10. This feature is in Alpha. It can be changed or removed at any time. A description. |
+
+ #### Fields with arguments
+
+ ##### `AlphaTest.fooWithArgs`
+
+ A description.
+
+ WARNING:
+ **Introduced** in 1.10.
+ This feature is in Alpha. It can be changed or removed at any time.
+
+ Returns [`String!`](#string).
+
+ ###### Arguments
+
+ | Name | Type | Description |
+ | ---- | ---- | ----------- |
+ | <a id="alphatestfoowithargsarg"></a>`arg` | [`Int`](#int) | Argity. |
+ DOC
+ end
+
+ it_behaves_like 'renders correctly as GraphQL documentation'
+ end
+
+ context 'when a Query.field is in alpha' do
+ before do
+ query_type.field(
+ name: :bar,
+ type: type,
+ null: true,
+ description: 'A bar',
+ alpha: { milestone: '10.11' }
+ )
+ end
+
+ let(:type) { ::GraphQL::Types::Int }
+ let(:section) do
+ <<~DOC
+ ### `Query.bar`
+
+ A bar.
+
+ WARNING:
+ **Introduced** in 10.11.
+ This feature is in Alpha. It can be changed or removed at any time.
+
+ Returns [`Int`](#int).
+ DOC
+ end
+
+ it_behaves_like 'renders correctly as GraphQL documentation'
+ end
+
context 'when a field has an Enumeration type' do
let(:type) do
enum_type = Class.new(Types::BaseEnum) do
diff --git a/tooling/graphql/docs/helper.rb b/tooling/graphql/docs/helper.rb
index e4f14129f3b8f..a76773ed28d95 100644
--- a/tooling/graphql/docs/helper.rb
+++ b/tooling/graphql/docs/helper.rb
@@ -315,14 +315,17 @@ def doc_reference(object, owner)
def render_deprecation(object, owner, context)
buff = []
deprecation = schema_deprecation(owner, object[:name])
+ original_description = deprecation&.original_description || render_description_of(object, owner)
- buff << (deprecation&.original_description || render_description_of(object, owner)) if context == :block
+ buff << original_description if context == :block
buff << if deprecation
deprecation.markdown(context: context)
else
"**Deprecated:** #{object[:deprecation_reason]}"
end
+ buff << original_description if context == :inline && deprecation&.alpha?
+
join(context, buff)
end
--
GitLab