Merge branch '30019-warn-about-stale-graphql-docs' into 'master'

Add test for stale GraphQL docs to CI

Closes #30019

See merge request gitlab-org/gitlab!18549

.gitlab/ci/docs.gitlab-ci.yml

@@ -67,3 +67,18 @@ docs lint:
     - bundle exec nanoc check internal_links
     # Check the internal anchor links
     - bundle exec nanoc check internal_anchors
+
+graphql-docs-verify:
+  extends:
+    - .default-tags
+    - .default-retry
+    - .default-cache
+    - .default-only
+    - .default-before_script
+    - .only-graphql-changes
+  variables:
+    SETUP_DB: "false"
+  stage: test
+  needs: ["setup-test-env"]
+  script:
+    - bundle exec rake gitlab:graphql:check_docs

.gitlab/ci/global.gitlab-ci.yml

@@ -71,6 +71,12 @@
       - "doc/**/*"
       - ".markdownlint.json"
 
+.only-graphql-changes:
+  only:
+    changes:
+      - "{,ee/}app/graphql/**/*"
+      - "{,ee/}lib/gitlab/graphql/**/*"
+
 .only-code-qa-changes:
   only:
     changes:

doc/api/graphql/reference/index.md

@@ -54,9 +54,87 @@ The API can be explored interactively using the [GraphiQL IDE](../index.md#graph
 | `message` | String |  |
 | `authoredDate` | Time |  |
 | `webUrl` | String! |  |
+| `signatureHtml` | String | Rendered html for the commit signature |
 | `author` | User |  |
 | `latestPipeline` | Pipeline | Latest pipeline for this commit |
 
+### CreateDiffNotePayload
+
+| Name  | Type  | Description |
+| ---   |  ---- | ----------  |
+| `clientMutationId` | String | A unique identifier for the client performing the mutation. |
+| `errors` | String! => Array | Reasons why the mutation failed. |
+| `note` | Note | The note after mutation |
+
+### CreateImageDiffNotePayload
+
+| Name  | Type  | Description |
+| ---   |  ---- | ----------  |
+| `clientMutationId` | String | A unique identifier for the client performing the mutation. |
+| `errors` | String! => Array | Reasons why the mutation failed. |
+| `note` | Note | The note after mutation |
+
+### CreateNotePayload
+
+| Name  | Type  | Description |
+| ---   |  ---- | ----------  |
+| `clientMutationId` | String | A unique identifier for the client performing the mutation. |
+| `errors` | String! => Array | Reasons why the mutation failed. |
+| `note` | Note | The note after mutation |
+
+### Design
+
+| Name  | Type  | Description |
+| ---   |  ---- | ----------  |
+| `id` | ID! |  |
+| `project` | Project! |  |
+| `issue` | Issue! |  |
+| `notesCount` | Int! | The total count of user-created notes for this design |
+| `filename` | String! |  |
+| `fullPath` | String! |  |
+| `event` | DesignVersionEvent! | The change that happened to the design at this version |
+| `image` | String! |  |
+| `diffRefs` | DiffRefs! |  |
+
+### DesignCollection
+
+| Name  | Type  | Description |
+| ---   |  ---- | ----------  |
+| `project` | Project! |  |
+| `issue` | Issue! |  |
+
+### DesignManagementDeletePayload
+
+| Name  | Type  | Description |
+| ---   |  ---- | ----------  |
+| `clientMutationId` | String | A unique identifier for the client performing the mutation. |
+| `errors` | String! => Array | Reasons why the mutation failed. |
+| `version` | DesignVersion | The new version in which the designs are deleted |
+
+### DesignManagementUploadPayload
+
+| Name  | Type  | Description |
+| ---   |  ---- | ----------  |
+| `clientMutationId` | String | A unique identifier for the client performing the mutation. |
+| `errors` | String! => Array | Reasons why the mutation failed. |
+| `designs` | Design! => Array | The designs that were uploaded by the mutation |
+| `skippedDesigns` | Design! => Array | Any designs that were skipped from the upload due to there being no change to their content since their last version |
+
+### DesignVersion
+
+| Name  | Type  | Description |
+| ---   |  ---- | ----------  |
+| `id` | ID! |  |
+| `sha` | ID! |  |
+
+### DestroyNotePayload
+
+| Name  | Type  | Description |
+| ---   |  ---- | ----------  |
+| `clientMutationId` | String | A unique identifier for the client performing the mutation. |
+| `errors` | String! => Array | Reasons why the mutation failed. |
+| `note` | Note | The note after mutation |
+
 ### DetailedStatus
 
 | Name  | Type  | Description |
@@ -74,9 +152,7 @@ The API can be explored interactively using the [GraphiQL IDE](../index.md#graph
 
 | Name  | Type  | Description |
 | ---   |  ---- | ----------  |
-| `headSha` | String! | The sha of the head at the time the comment was made |
-| `baseSha` | String | The merge base of the branch the comment was made on |
-| `startSha` | String! | The sha of the branch being compared against |
+| `diffRefs` | DiffRefs! |  |
 | `filePath` | String! | The path of the file that was changed |
 | `oldPath` | String | The path of the file on the start sha. |
 | `newPath` | String | The path of the file on the head sha. |
@@ -88,13 +164,146 @@ The API can be explored interactively using the [GraphiQL IDE](../index.md#graph
 | `width` | Int | The total width of the image |
 | `height` | Int | The total height of the image |
 
+### DiffRefs
+
+| Name  | Type  | Description |
+| ---   |  ---- | ----------  |
+| `headSha` | String! | The sha of the head at the time the comment was made |
+| `baseSha` | String! | The merge base of the branch the comment was made on |
+| `startSha` | String! | The sha of the branch being compared against |
+
 ### Discussion
 
 | Name  | Type  | Description |
 | ---   |  ---- | ----------  |
 | `id` | ID! |  |
+| `replyId` | ID! | The ID used to reply to this discussion |
 | `createdAt` | Time! |  |
 
+### Epic
+
+| Name  | Type  | Description |
+| ---   |  ---- | ----------  |
+| `userPermissions` | EpicPermissions! | Permissions for the current user on the resource |
+| `id` | ID! |  |
+| `iid` | ID! |  |
+| `title` | String |  |
+| `description` | String |  |
+| `state` | EpicState! |  |
+| `group` | Group! |  |
+| `parent` | Epic |  |
+| `author` | User! |  |
+| `startDate` | Time |  |
+| `startDateIsFixed` | Boolean |  |
+| `startDateFixed` | Time |  |
+| `startDateFromMilestones` | Time |  |
+| `dueDate` | Time |  |
+| `dueDateIsFixed` | Boolean |  |
+| `dueDateFixed` | Time |  |
+| `dueDateFromMilestones` | Time |  |
+| `closedAt` | Time |  |
+| `createdAt` | Time |  |
+| `updatedAt` | Time |  |
+| `hasChildren` | Boolean! |  |
+| `hasIssues` | Boolean! |  |
+| `webPath` | String! |  |
+| `webUrl` | String! |  |
+| `relativePosition` | Int | The relative position of the epic in the Epic tree |
+| `relationPath` | String |  |
+| `reference` | String! |  |
+
+### EpicIssue
+
+| Name  | Type  | Description |
+| ---   |  ---- | ----------  |
+| `userPermissions` | IssuePermissions! | Permissions for the current user on the resource |
+| `iid` | ID! |  |
+| `title` | String! |  |
+| `titleHtml` | String | The GitLab Flavored Markdown rendering of `title` |
+| `description` | String |  |
+| `descriptionHtml` | String | The GitLab Flavored Markdown rendering of `description` |
+| `state` | IssueState! |  |
+| `reference` | String! |  |
+| `author` | User! |  |
+| `milestone` | Milestone |  |
+| `dueDate` | Time |  |
+| `confidential` | Boolean! |  |
+| `discussionLocked` | Boolean! |  |
+| `upvotes` | Int! |  |
+| `downvotes` | Int! |  |
+| `userNotesCount` | Int! |  |
+| `webPath` | String! |  |
+| `webUrl` | String! |  |
+| `relativePosition` | Int |  |
+| `timeEstimate` | Int! | The time estimate on the issue |
+| `totalTimeSpent` | Int! | Total time reported as spent on the issue |
+| `closedAt` | Time |  |
+| `createdAt` | Time! |  |
+| `updatedAt` | Time! |  |
+| `taskCompletionStatus` | TaskCompletionStatus! |  |
+| `epic` | Epic | The epic to which issue belongs |
+| `weight` | Int |  |
+| `designs` | DesignCollection |  |
+| `designCollection` | DesignCollection |  |
+| `epicIssueId` | ID! |  |
+| `relationPath` | String |  |
+| `id` | ID | The global id of the epic-issue relation |
+
+### EpicPermissions
+
+| Name  | Type  | Description |
+| ---   |  ---- | ----------  |
+| `readEpic` | Boolean! | Whether or not a user can perform `read_epic` on this resource |
+| `readEpicIid` | Boolean! | Whether or not a user can perform `read_epic_iid` on this resource |
+| `updateEpic` | Boolean! | Whether or not a user can perform `update_epic` on this resource |
+| `destroyEpic` | Boolean! | Whether or not a user can perform `destroy_epic` on this resource |
+| `adminEpic` | Boolean! | Whether or not a user can perform `admin_epic` on this resource |
+| `createEpic` | Boolean! | Whether or not a user can perform `create_epic` on this resource |
+| `createNote` | Boolean! | Whether or not a user can perform `create_note` on this resource |
+| `awardEmoji` | Boolean! | Whether or not a user can perform `award_emoji` on this resource |
+
+### EpicTreeReorderPayload
+
+| Name  | Type  | Description |
+| ---   |  ---- | ----------  |
+| `clientMutationId` | String | A unique identifier for the client performing the mutation. |
+| `errors` | String! => Array | Reasons why the mutation failed. |
+
+### ExtendedIssue
+
+| Name  | Type  | Description |
+| ---   |  ---- | ----------  |
+| `userPermissions` | IssuePermissions! | Permissions for the current user on the resource |
+| `iid` | ID! |  |
+| `title` | String! |  |
+| `titleHtml` | String | The GitLab Flavored Markdown rendering of `title` |
+| `description` | String |  |
+| `descriptionHtml` | String | The GitLab Flavored Markdown rendering of `description` |
+| `state` | IssueState! |  |
+| `reference` | String! |  |
+| `author` | User! |  |
+| `milestone` | Milestone |  |
+| `dueDate` | Time |  |
+| `confidential` | Boolean! |  |
+| `discussionLocked` | Boolean! |  |
+| `upvotes` | Int! |  |
+| `downvotes` | Int! |  |
+| `userNotesCount` | Int! |  |
+| `webPath` | String! |  |
+| `webUrl` | String! |  |
+| `relativePosition` | Int |  |
+| `timeEstimate` | Int! | The time estimate on the issue |
+| `totalTimeSpent` | Int! | Total time reported as spent on the issue |
+| `closedAt` | Time |  |
+| `createdAt` | Time! |  |
+| `updatedAt` | Time! |  |
+| `taskCompletionStatus` | TaskCompletionStatus! |  |
+| `epic` | Epic | The epic to which issue belongs |
+| `weight` | Int |  |
+| `designs` | DesignCollection |  |
+| `designCollection` | DesignCollection |  |
+| `subscribed` | Boolean! | Boolean flag for whether the currently logged in user is subscribed to this issue |
+
 ### Group
 
 | Name  | Type  | Description |
@@ -109,11 +318,13 @@ The API can be explored interactively using the [GraphiQL IDE](../index.md#graph
 | `visibility` | String |  |
 | `lfsEnabled` | Boolean |  |
 | `requestAccessEnabled` | Boolean |  |
-| `rootStorageStatistics` | RootStorageStatistics | The aggregated storage statistics. Only available if the namespace has no parent |
+| `rootStorageStatistics` | RootStorageStatistics | The aggregated storage statistics. Only available for root namespaces |
 | `userPermissions` | GroupPermissions! | Permissions for the current user on the resource |
 | `webUrl` | String! |  |
 | `avatarUrl` | String |  |
 | `parent` | Group |  |
+| `epicsEnabled` | Boolean |  |
+| `epic` | Epic |  |
 
 ### GroupPermissions
 
@@ -144,10 +355,16 @@ The API can be explored interactively using the [GraphiQL IDE](../index.md#graph
 | `webPath` | String! |  |
 | `webUrl` | String! |  |
 | `relativePosition` | Int |  |
+| `timeEstimate` | Int! | The time estimate on the issue |
+| `totalTimeSpent` | Int! | Total time reported as spent on the issue |
 | `closedAt` | Time |  |
 | `createdAt` | Time! |  |
 | `updatedAt` | Time! |  |
 | `taskCompletionStatus` | TaskCompletionStatus! |  |
+| `epic` | Epic | The epic to which issue belongs |
+| `weight` | Int |  |
+| `designs` | DesignCollection |  |
+| `designCollection` | DesignCollection |  |
 
 ### IssuePermissions
 
@@ -158,6 +375,9 @@ The API can be explored interactively using the [GraphiQL IDE](../index.md#graph
 | `updateIssue` | Boolean! | Whether or not a user can perform `update_issue` on this resource |
 | `createNote` | Boolean! | Whether or not a user can perform `create_note` on this resource |
 | `reopenIssue` | Boolean! | Whether or not a user can perform `reopen_issue` on this resource |
+| `readDesign` | Boolean! | Whether or not a user can perform `read_design` on this resource |
+| `createDesign` | Boolean! | Whether or not a user can perform `create_design` on this resource |
+| `destroyDesign` | Boolean! | Whether or not a user can perform `destroy_design` on this resource |
 
 ### Label
 
@@ -185,6 +405,7 @@ The API can be explored interactively using the [GraphiQL IDE](../index.md#graph
 | `updatedAt` | Time! |  |
 | `sourceProject` | Project |  |
 | `targetProject` | Project! |  |
+| `diffRefs` | DiffRefs |  |
 | `project` | Project! |  |
 | `projectId` | Int! |  |
 | `sourceProjectId` | Int |  |
@@ -271,6 +492,7 @@ The API can be explored interactively using the [GraphiQL IDE](../index.md#graph
 | `visibility` | String |  |
 | `lfsEnabled` | Boolean |  |
 | `requestAccessEnabled` | Boolean |  |
+| `rootStorageStatistics` | RootStorageStatistics | The aggregated storage statistics. Only available for root namespaces |
 
 ### Note
 
@@ -381,7 +603,7 @@ The API can be explored interactively using the [GraphiQL IDE](../index.md#graph
 | `statistics` | ProjectStatistics |  |
 | `repository` | Repository |  |
 | `mergeRequest` | MergeRequest |  |
-| `issue` | Issue |  |
+| `issue` | ExtendedIssue |  |
 
 ### ProjectPermissions
 
@@ -424,6 +646,10 @@ The API can be explored interactively using the [GraphiQL IDE](../index.md#graph
 | `createPages` | Boolean! | Whether or not a user can perform `create_pages` on this resource |
 | `destroyPages` | Boolean! | Whether or not a user can perform `destroy_pages` on this resource |
 | `readPagesContent` | Boolean! | Whether or not a user can perform `read_pages_content` on this resource |
+| `adminOperations` | Boolean! | Whether or not a user can perform `admin_operations` on this resource |
+| `readDesign` | Boolean! | Whether or not a user can perform `read_design` on this resource |
+| `createDesign` | Boolean! | Whether or not a user can perform `create_design` on this resource |
+| `destroyDesign` | Boolean! | Whether or not a user can perform `destroy_design` on this resource |
 
 ### ProjectStatistics
 
@@ -458,12 +684,12 @@ The API can be explored interactively using the [GraphiQL IDE](../index.md#graph
 
 | Name  | Type  | Description |
 | ---   |  ---- | ----------  |
-| `storageSize` | Int! | The total storage in Bytes |
-| `repositorySize` | Int! | The Git repository size in Bytes |
-| `lfsObjectsSize` | Int! | The LFS objects size in Bytes |
-| `buildArtifactsSize` | Int! | The CI artifacts size in Bytes |
-| `packagesSize` | Int! | The packages size in Bytes |
-| `wikiSize` | Int! | The wiki size in Bytes |
+| `storageSize` | Int! | The total storage in bytes |
+| `repositorySize` | Int! | The git repository size in bytes |
+| `lfsObjectsSize` | Int! | The LFS objects size in bytes |
+| `buildArtifactsSize` | Int! | The CI artifacts size in bytes |
+| `packagesSize` | Int! | The packages size in bytes |
+| `wikiSize` | Int! | The wiki size in bytes |
 
 ### Submodule
 
@@ -474,6 +700,8 @@ The API can be explored interactively using the [GraphiQL IDE](../index.md#graph
 | `type` | EntryType! |  |
 | `path` | String! |  |
 | `flatPath` | String! |  |
+| `webUrl` | String |  |
+| `treeUrl` | String |  |
 
 ### TaskCompletionStatus
 
@@ -495,7 +723,7 @@ The API can be explored interactively using the [GraphiQL IDE](../index.md#graph
 
 | Name  | Type  | Description |
 | ---   |  ---- | ----------  |
-| `lastCommit` | Commit |  |
+| `lastCommit` | Commit | Last commit for the tree |
 
 ### TreeEntry
 
@@ -508,6 +736,14 @@ The API can be explored interactively using the [GraphiQL IDE](../index.md#graph
 | `flatPath` | String! |  |
 | `webUrl` | String |  |
 
+### UpdateNotePayload
+
+| Name  | Type  | Description |
+| ---   |  ---- | ----------  |
+| `clientMutationId` | String | A unique identifier for the client performing the mutation. |
+| `errors` | String! => Array | Reasons why the mutation failed. |
+| `note` | Note | The note after mutation |
+
 ### User
 
 | Name  | Type  | Description |

doc/development/pipelines.md

@@ -115,6 +115,7 @@ from a commit or MR by extending from the following CI definitions:
 - `.only-qa-changes`: Allows a job to only be created upon QA-related changes.
 - `.only-docs-changes`: Allows a job to only be created upon docs-related changes.
 - `.only-code-qa-changes`: Allows a job to only be created upon code-related or QA-related changes.
+- `.only-graphql-changes`: Allows a job to only be created upon graphql-related changes.
 
 **See <https://gitlab.com/gitlab-org/gitlab/blob/master/.gitlab/ci/global.gitlab-ci.yml>
 for the list of exact patterns.**
@@ -175,6 +176,7 @@ subgraph "`test` stage"
     db:* --> |needs| A;
     gitlab:setup --> |needs| A;
     downtime_check --> |needs and depends on| A;
+    graphql-docs-verify --> |needs| A;
     end
 
 subgraph "`review-prepare` stage"

lib/gitlab/graphql/docs/renderer.rb

@@ -23,15 +23,12 @@ module Gitlab
           @parsed_schema = GraphQLDocs::Parser.new(schema, {}).parse
         end
 
-        def render
-          contents = @layout.render(self)
-
-          write_file(contents)
+        def contents
+          # Render and remove an extra trailing new line
+          @contents ||= @layout.render(self).sub!(/\n(?=\Z)/, '')
         end
 
-        private
-
-        def write_file(contents)
+        def write
           filename = File.join(@output_dir, 'index.md')
 
           FileUtils.mkdir_p(@output_dir)

lib/gitlab/graphql/docs/templates/default.md.haml

@@ -20,6 +20,3 @@
     - type[:fields].each do |field|
       = "| `#{field[:name]}` | #{render_field_type(field[:type][:info])} | #{field[:description]} |"
     \
-
-
-

lib/tasks/gitlab/graphql.rake

@@ -11,10 +11,28 @@ namespace :gitlab do
     task compile_docs: :environment do
       renderer = Gitlab::Graphql::Docs::Renderer.new(GitlabSchema.graphql_definition, render_options)
 
-      renderer.render
+      renderer.write
 
       puts "Documentation compiled."
     end
+
+    desc 'GitLab | Check if GraphQL docs are up to date'
+    task check_docs: :environment do
+      renderer = Gitlab::Graphql::Docs::Renderer.new(GitlabSchema.graphql_definition, render_options)
+
+      doc = File.read(Rails.root.join(OUTPUT_DIR, 'index.md'))
+
+      if doc == renderer.contents
+        puts "GraphQL documentation is up to date"
+      else
+        puts '#' * 10
+        puts '#'
+        puts '# GraphQL documentation is outdated! Please update it by running `bundle exec rake gitlab:graphql:compile_docs`.'
+        puts '#'
+        puts '#' * 10
+        abort
+      end
+    end
   end
 end