We have a lot of GraphQL descriptions missing from the documentation. ``` $ without=$(grep '"description": null' doc/api/graphql/reference/gitlab_schema.json | wc -l); echo $without 596 $ with=$(grep '"description": ' doc/api/graphql/reference/gitlab_schema.json | grep -v null | wc -l); echo $with 5563 $ echo -e "scale=3\n$without / $with" | bc .107 ``` Ideally, we want descriptions for everything and to avoid introduction of more empty descriptions without having to rely on reviewers noticing it. ### Proposal 1. [x] Add missing descriptions (see below if you want to contribute an MR). 1. [ ] Prioritise [GraphQL description cop misses missing description from declaration methods](https://gitlab.com/gitlab-org/gitlab/-/issues/35321). 1. [ ] Prioritise [Cop to enforce GraphQL type description presence](https://gitlab.com/gitlab-org/gitlab/-/issues/220006). 1. [ ] While the above isn't in place, request that reviewers flag missing GraphQL documentation as a blocking MR issue. 1. [ ] Recommend SSOT for documentation of GraphQL `Enum` types used in multiple places. This can be made easier by using [`DeclarativeEnum`](https://gitlab.com/gitlab-org/gitlab/-/blob/1ae7050ea0db183598942fcecb49cb044532f79c/lib/declarative_enum.rb). Example: [GraphQL Type](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/app/graphql/types/vulnerabilities/dismissal_reason_enum.rb), [Active Record model](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/app/models/vulnerabilities/feedback.rb#L19). 1. [ ] Refactor existing GraphQL `Enum` types (see below if you want to contribute). ### Help wanted Everyone can contribute! If you can afford to spend some time helping, please place your name next to one of the items so others know you're working on it. If you're an engineer and believe one of the suggested refactors is worth doing, please link your WIP MR so no one else picks it up. #### Missing descriptions This list might not be complete. Once the cop is working, we could find others. | File | DRI | MR | | ------ | ------ | ------ | | [access_level_enum.rb](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/graphql/types/access_level_enum.rb) | @jschafer | !54988 | | [type_enum.rb](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/graphql/types/blob_viewers/type_enum.rb) | @subashis | !55006 | | [job_artifact_file_type_enum.rb](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/graphql/types/ci/job_artifact_file_type_enum.rb) | @subashis | !55012 | | [pipeline_config_source_enum.rb](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/graphql/types/ci/pipeline_config_source_enum.rb) | @subashis | !57003 | | [pipeline_status_enum.rb](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/graphql/types/ci/pipeline_status_enum.rb) | @jschafer | !57876 | | [ui_component_size_enum.rb](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/graphql/types/ci_configuration/sast/ui_component_size_enum.rb) | @subashis | !54184 | | [issuable_state_enum.rb](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/graphql/types/issuable_state_enum.rb) | @jschafer | !53303 | | [merge_request_state_enum.rb](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/graphql/types/merge_request_state_enum.rb) | @jschafer | !53082 | | [milestone_state_enum.rb](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/graphql/types/milestone_state_enum.rb) | @mwoolf | !52494, !53287 | | [position_type_enum.rb](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/graphql/types/notes/position_type_enum.rb) | @quintasan | !56103 | | [service_type_enum.rb](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/graphql/types/projects/service_type_enum.rb) | @arturoherrero | !53515 | | [todo_action_enum.rb](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/graphql/types/todo_action_enum.rb) | @thiagocsf | !55030 | | [todo_state_enum.rb](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/graphql/types/todo_state_enum.rb) | @subashis | !54178 | | [type_enum.rb](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/graphql/types/tree/type_enum.rb) | @jschafer | !60150 | | [visibility_levels_enum.rb](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/graphql/types/visibility_levels_enum.rb) | @subashis | !54630 | | [base_enum.rb](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/graphql/types/base_enum.rb) | @jschafer | !60838 | | [container_expiration_policy_cadence_enum.rb](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/graphql/types/container_expiration_policy_cadence_enum.rb) | @jschafer | !61073 | | [container_expiration_policy_keep_enum.rb](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/graphql/types/container_expiration_policy_keep_enum.rb) | @jschafer | !61073 | | [container_expiration_policy_older_than_enum.rb](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/graphql/types/container_expiration_policy_older_than_enum.rb) | @jschafer | !61073 | | [package_type_enum.rb](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/graphql/types/packages/package_type_enum.rb) | @jschafer | !61073 | | [blob_action_enum.rb](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/graphql/types/snippets/blob_action_enum.rb) | @jschafer | !61817 | | [type_enum.rb](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/graphql/types/snippets/type_enum.rb) | @jschafer | !61820 | | [visibility_scopes_enum.rb](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/graphql/types/snippets/visibility_scopes_enum.rb) | @jschafer | !61825 | | [list_limit_metric_enum.rb](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/app/graphql/ee/types/list_limit_metric_enum.rb) | @jschafer | !63882 | | [payload_alert_field_name_enum.rb](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/app/graphql/types/alert_management/payload_alert_field_name_enum.rb) | @jschafer | !61073 | | [epic_state_enum.rb](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/app/graphql/types/epic_state_enum.rb) | @jschafer | !63915 | | [health_status_enum.rb](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/app/graphql/types/health_status_enum.rb) | Your Name | MR | | [iteration_state_enum.rb](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/app/graphql/types/iteration_state_enum.rb) | Your Name | MR | | [requirement_state_enum.rb](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/app/graphql/types/requirements_management/requirement_state_enum.rb) | Your Name | MR | | [test_report_state_enum.rb](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/app/graphql/types/requirements_management/test_report_state_enum.rb) | Your Name | MR | | [security_scanner_type_enum.rb](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/app/graphql/types/security_scanner_type_enum.rb) | Your Name | MR | | [issue_link_type_enum.rb](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/app/graphql/types/vulnerability/issue_link_type_enum.rb) | Your Name | MR | | [vulnerability_grade_enum.rb](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/app/graphql/types/vulnerability_grade_enum.rb) | Your Name | MR | | [vulnerability_report_type_enum.rb](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/app/graphql/types/vulnerability_report_type_enum.rb) | Your Name | MR | | [vulnerability_severity_enum.rb](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/app/graphql/types/vulnerability_severity_enum.rb) | Your Name | MR | | [vulnerability_state_enum.rb](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/app/graphql/types/vulnerability_state_enum.rb) | Your Name | MR | #### Review generated descriptions These have been generated using values from other fields. Some of them could do with a better explanation of what the choice means/does. | File | Reviewed by | :white_check_mark: or MR, if updates made | | ------ | ------ | ------ | | [status_enum.rb](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/graphql/types/alert_management/status_enum.rb) | @jschafer | !60152 | | [severity_enum.rb](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/graphql/types/alert_management/severity_enum.rb) | @jschafer | :white_check_mark: | | [availability_enum.rb](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/graphql/types/availability_enum.rb) | @jschafer | :white_check_mark: | | [container_repository_status_enum.rb](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/graphql/types/container_repository_status_enum.rb) | @jschafer | :white_check_mark: | | [design_collection_copy_state_enum.rb](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/graphql/types/design_management/design_collection_copy_state_enum.rb) | @jschafer | :white_check_mark: | | [design_version_event_enum.rb](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/graphql/types/design_management/design_version_event_enum.rb) | @jschafer | :white_check_mark: | | [group_member_relation_enum.rb](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/graphql/types/group_member_relation_enum.rb) | @jschafer | !60158 | | [release_asset_link_type_enum.rb](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/graphql/types/release_asset_link_type_enum.rb) | @jschafer | :white_check_mark: | | [report_type_enum.rb](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/graphql/types/security/report_type_enum.rb) | @jschafer | :white_check_mark: | #### Suggested refactoring [DRY-up `app/graphql/types/todo_action_enum.rb`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/55030#note_515746185) - https://gitlab.com/gitlab-org/gitlab/-/blob/3a671200233b6d7b83ef247884e70bc7f905c47f/app/models/todo.rb#L19-20 - https://gitlab.com/gitlab-org/gitlab/-/blob/3a671200233b6d7b83ef247884e70bc7f905c47f/app/graphql/types/todo_action_enum.rb Maybe move to `ee/app/enums/`? - https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/app/graphql/ee/types/todo_target_enum.rb - https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/graphql/types/todo_target_enum.rb Maybe DRY-up? - https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/graphql/types/snippets/visibility_scopes_enum.rb#L5 - https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/models/snippet.rb#L78-79 - https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/visibility_level.rb#L22-24 Maybe DRY-UP? - https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/models/snippet_input_action.rb#L6 - https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/graphql/types/commit_action_mode_enum.rb Maybe use `DeclarativeEnum`? - https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/graphql/resolvers/error_tracking/sentry_errors_resolver.rb#L14 Maybe use `DeclarativeEnum`? - https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/models/container_expiration_policy.rb#L41 - https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/graphql/types/container_expiration_policy_cadence_enum.rb - https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/graphql/types/container_expiration_policy_keep_enum.rb Maybe use `DeclarativeEnum`? - https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/models/issue.rb - https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/graphql/types/issue_type_enum.rb Maybe use `DeclarativeEnum`? - https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/models/concerns/enums/data_visualization_palette.rb - https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/graphql/types/data_visualization_palette/color_enum.rb - https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/graphql/types/data_visualization_palette/weight_enum.rb Maybe use `DeclarativeEnum`? - https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/models/issuable_severity.rb - https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/graphql/types/issuable_severity_enum.rb