Skip to content

Over 10% of GraphQL descriptions are missing

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. Add missing descriptions (see below if you want to contribute an MR).
  2. Prioritise GraphQL description cop misses missing description from declaration methods.
  3. Prioritise Cop to enforce GraphQL type description presence.
  4. While the above isn't in place, request that reviewers flag missing GraphQL documentation as a blocking MR issue.
  5. Recommend SSOT for documentation of GraphQL Enum types used in multiple places. This can be made easier by using DeclarativeEnum. Example: GraphQL Type, Active Record model.
  6. 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 @jschafer !54988 (merged)
type_enum.rb @subashis !55006 (merged)
job_artifact_file_type_enum.rb @subashis !55012 (merged)
pipeline_config_source_enum.rb @subashis !57003 (merged)
pipeline_status_enum.rb @jschafer !57876 (merged)
ui_component_size_enum.rb @subashis !54184 (merged)
issuable_state_enum.rb @jschafer !53303 (merged)
merge_request_state_enum.rb @jschafer !53082 (merged)
milestone_state_enum.rb @mwoolf !52494 (merged), !53287 (merged)
position_type_enum.rb @Quintasan !56103 (merged)
service_type_enum.rb @arturoherrero !53515 (merged)
todo_action_enum.rb @thiagocsf !55030 (merged)
todo_state_enum.rb @subashis !54178 (merged)
type_enum.rb @jschafer !60150 (merged)
visibility_levels_enum.rb @subashis !54630 (merged)
base_enum.rb @jschafer !60838 (merged)
container_expiration_policy_cadence_enum.rb @jschafer !61073 (merged)
container_expiration_policy_keep_enum.rb @jschafer !61073 (merged)
container_expiration_policy_older_than_enum.rb @jschafer !61073 (merged)
package_type_enum.rb @jschafer !61073 (merged)
blob_action_enum.rb @jschafer !61817 (merged)
type_enum.rb @jschafer !61820 (merged)
visibility_scopes_enum.rb @jschafer !61825 (merged)
list_limit_metric_enum.rb @jschafer !63882 (merged)
payload_alert_field_name_enum.rb @jschafer !61073 (merged)
epic_state_enum.rb @jschafer !63915 (merged)
health_status_enum.rb Your Name MR
iteration_state_enum.rb Your Name MR
requirement_state_enum.rb Your Name MR
test_report_state_enum.rb Your Name MR
security_scanner_type_enum.rb Your Name MR
issue_link_type_enum.rb Your Name MR
vulnerability_grade_enum.rb Your Name MR
vulnerability_report_type_enum.rb Your Name MR
vulnerability_severity_enum.rb Your Name MR
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 ✅ or MR, if updates made
status_enum.rb @jschafer !60152 (merged)
severity_enum.rb @jschafer ✅
availability_enum.rb @jschafer ✅
container_repository_status_enum.rb @jschafer ✅
design_collection_copy_state_enum.rb @jschafer ✅
design_version_event_enum.rb @jschafer ✅
group_member_relation_enum.rb @jschafer !60158 (merged)
release_asset_link_type_enum.rb @jschafer ✅
report_type_enum.rb @jschafer ✅

Suggested refactoring

DRY-up app/graphql/types/todo_action_enum.rb

Maybe move to ee/app/enums/?

Maybe DRY-up?

Maybe DRY-UP?

Maybe use DeclarativeEnum?

Maybe use DeclarativeEnum?

Maybe use DeclarativeEnum?

Maybe use DeclarativeEnum?

Maybe use DeclarativeEnum?

Edited by Thiago Figueiró