docs(graphql): ensure descriptions for all types with opt-in enforcem…

…ent (#8349)

python_modules/dagster-graphql/dagster_graphql/schema/pipelines/status.py

@@ -1,8 +1,12 @@
 # pylint: disable=missing-graphene-docstring
 import graphene
 
+import dagster._check as check
+
 
 class GrapheneRunStatus(graphene.Enum):
+    """The status of run execution."""
+
     QUEUED = "QUEUED"
     NOT_STARTED = "NOT_STARTED"
     MANAGED = "MANAGED"
@@ -15,3 +19,26 @@ class GrapheneRunStatus(graphene.Enum):
 
     class Meta:
         name = "RunStatus"
+
+    @property
+    def description(self: "GrapheneRunStatus") -> str:
+        if self == GrapheneRunStatus.QUEUED:
+            return "Runs waiting to be launched by the Dagster Daemon."
+        elif self == GrapheneRunStatus.NOT_STARTED:
+            return "Runs that have been created, but not yet submitted for launch."
+        elif self == GrapheneRunStatus.MANAGED:
+            return "Runs that are managed outside of the Dagster control plane."
+        elif self == GrapheneRunStatus.STARTING:
+            return "Runs that have been launched, but execution has not yet started."
+        elif self == GrapheneRunStatus.STARTED:
+            return "Runs that have been launched and execution has started."
+        elif self == GrapheneRunStatus.SUCCESS:
+            return "Runs that have successfully completed."
+        elif self == GrapheneRunStatus.FAILURE:
+            return "Runs that have failed to complete."
+        elif self == GrapheneRunStatus.CANCELING:
+            return "Runs that are in-progress and pending to be canceled."
+        elif self == GrapheneRunStatus.CANCELED:
+            return "Runs that have been canceled before completion."
+        else:
+            check.assert_never(self)

python_modules/dagster-graphql/dagster_graphql_tests/test_schema.py

@@ -3,6 +3,9 @@
 import pytest
 from click.testing import CliRunner
 from dagster_graphql.cli import ui
+from dagster_graphql.schema.pipelines.status import GrapheneRunStatus
+
+GRAPHQL_TYPES_TO_ENFORCE_DESCRIPTION = {str(graphene_type) for graphene_type in [GrapheneRunStatus]}
 
 
 @pytest.fixture(name="runner")
@@ -37,6 +40,58 @@ def test_schema_type_names_without_graphene(runner):
     ), f"'Graphene' cannot be included in the GraphQL type name. Violating types: {violations}."
 
 
+def test_schema_types_have_descriptions(runner):
+    """
+    This test is opt-in right now, but once we have enough descriptions under test, we can
+    switch this to be opt-out.
+    """
+    query = """
+    query GetSchemaTypeDescriptions {
+        __schema {
+            types {
+                name
+                description
+                enumValues {
+                    name
+                    description
+                }
+            }
+        }
+    }
+    """
+
+    result = runner.invoke(
+        ui,
+        ["--empty-workspace", "--ephemeral-instance", "-t", query],
+    )
+    graphql_schema_types = json.loads(result.output)["data"]["__schema"]["types"]
+
+    filtered_graphql_schema_types = [
+        graphql_type
+        for graphql_type in graphql_schema_types
+        if graphql_type["name"] in GRAPHQL_TYPES_TO_ENFORCE_DESCRIPTION
+    ]
+
+    violations = [
+        graphql_type["name"]
+        for graphql_type in filtered_graphql_schema_types
+        if not graphql_type["description"]
+    ]
+    assert (
+        not violations
+    ), f"Descriptions must be included in the GraphQL types. Violating types: {violations}."
+
+    enum_violations = [
+        f"{graphql_type['name']}.{enum_value['name']}"
+        for graphql_type in filtered_graphql_schema_types
+        for enum_value in graphql_type.get("enumValues", [])
+        if not enum_value["description"]
+    ]
+    assert (
+        not enum_violations
+    ), f"Descriptions must be included in the GraphQL enum values. Violating types: {enum_violations}."
+
+
 @pytest.mark.parametrize("operation_type", ["queryType", "mutationType", "subscriptionType"])
 def test_schema_operation_fields_have_descriptions(runner, operation_type):
     query = f"""

python_modules/dagster/dagster/core/storage/pipeline_run.py

@@ -61,16 +61,33 @@ def value_to_storage_str(
 
 @whitelist_for_serdes(serializer=DagsterRunStatusSerializer)
 class DagsterRunStatus(Enum):
-    """The status of pipeline execution."""
+    """The status of run execution."""
 
+    # Runs waiting to be launched by the Dagster Daemon.
     QUEUED = "QUEUED"
+
+    # Runs that have been launched, but execution has not yet started."""
     NOT_STARTED = "NOT_STARTED"
+
+    # Runs that are managed outside of the Dagster control plane.
     MANAGED = "MANAGED"
+
+    # Runs that have been launched, but execution has not yet started.
     STARTING = "STARTING"
+
+    # Runs that have been launched and execution has started.
     STARTED = "STARTED"
+
+    # Runs that have successfully completed.
     SUCCESS = "SUCCESS"
+
+    # Runs that have failed to complete.
     FAILURE = "FAILURE"
+
+    # Runs that are in-progress and pending to be canceled.
     CANCELING = "CANCELING"
+
+    # Runs that have been canceled before completion.
     CANCELED = "CANCELED"