Merge branch 'main' into schema_coordinates_spec_edit

Author: benjie

.github/algorithm-format-check.mjs

@@ -2,6 +2,9 @@ import { readFile, readdir } from "node:fs/promises";
 
 const SPEC_DIR = new URL("../spec", import.meta.url).pathname;
 
+/** @see {@link https://spec-md.com/#sec-Value-Literals} */
+const valueLiteralsRegexp = /\{((?:[^{}]|(?:\{[^{}]*\}))+)\}/g;
+
 process.exitCode = 0;
 const filenames = await readdir(SPEC_DIR);
 for (const filename of filenames) {
@@ -72,6 +75,33 @@ for (const filename of filenames) {
             console.log();
             process.exitCode = 1;
           }
+
+          const stepWithoutValueLiterals = step.replace(
+            valueLiteralsRegexp,
+            ""
+          );
+          if (stepWithoutValueLiterals.match(/\b[A-Z][A-Za-z0-9]+\(/)) {
+            console.log(
+              `Bad formatting of '${algorithmName}' step (algorithm call should be wrapped in braces: \`{MyAlgorithm(a, b, c)}\`) in '${filename}':`
+            );
+            console.dir(step);
+            console.log();
+            process.exitCode = 1;
+          }
+
+          const valueLiterals = step.matchAll(valueLiteralsRegexp, "");
+          for (const lit of valueLiterals) {
+            const inner = lit[1];
+            if (inner.includes("{")) {
+              console.log(
+                `Bad formatting of '${algorithmName}' step (algorithm call should not contain braces: \`${lit}\`) in '${filename}':`
+              );
+              console.dir(step);
+              console.log();
+              process.exitCode = 1;
+            }
+          }
+
           const trimmedInnerLine = step.replace(/\s+/g, " ");
           if (
             trimmedInnerLine.match(

CONTRIBUTING.md

@@ -6,8 +6,9 @@ contributions.
 
 Contributions that do not change the interpretation of the spec but instead
 improve legibility, fix editorial errors, clear up ambiguity and improve
-examples are encouraged and are often merged by a spec editor with little
-process.
+examples are encouraged. These "editorial changes" will normally be given the
+["✏ Editorial" label](https://github.com/graphql/graphql-spec/issues?q=sort%3Aupdated-desc+is%3Aopen+label%3A%22%E2%9C%8F%EF%B8%8F+Editorial%22)
+and are often merged by a spec editor with little process.
 
 However, contributions that _do_ meaningfully change the interpretation of the
 spec must follow an RFC (Request For Comments) process led by a _champion_

README.md

@@ -1,4 +1,4 @@
-[![GraphQLConf 2024 Banner: September 10-12, San Francisco. Hosted by the GraphQL Foundation](https://github.com/user-attachments/assets/0203f10b-ae1e-4fe1-9222-6547fa2bbd5d)](https://graphql.org/conf/2024/?utm_source=github&utm_medium=graphql_spec&utm_campaign=readme)
+[![GraphQLConf 2025 Banner: September 08-10, Amsterdam. Hosted by the GraphQL Foundation](./assets/graphql.org_conf_2025_.png)](https://graphql.org/conf/2025/?utm_source=github&utm_medium=graphql_js&utm_campaign=readme)
 
 # GraphQL
 

STYLE_GUIDE.md

@@ -82,3 +82,25 @@ MyAlgorithm(argOne, argTwo):
     - Let {something} be {true}.
 - Return {something}.
 ```
+
+## Definitions
+
+For important terms, use
+[Spec Markdown definition paragraphs](https://spec-md.com/#sec-Definition-Paragraph).
+
+Definition paragraphs start with `::` and add the matching italicized term to
+the [specification index](https://spec.graphql.org/draft/#index), making it easy
+to reference them.
+
+## Tone of voice
+
+The GraphQL specification is a reference document and should use neutral and
+descriptive tone of voice.
+
+**Favor the present tense**
+
+The present tense is usually clearer and shorter:
+
+✅ Present: The client then sends a request to the server.
+
+❌ Future: The client will then send a request to the server.

assets/graphql.org_conf_2025_.png

@@ -479,8 +479,9 @@ These two operations are semantically identical:
 
 Alias : Name :
 
-By default a field's response key in the response object will use that field's
-name. However, you can define a different response key by specifying an alias.
+:: A _response name_ is the key in the response object which correlates with a
+field's result. By default the response name will use the field's name; however,
+you can define a different response name by specifying an alias.
 
 In this example, we can fetch two profile pictures of different sizes and ensure
 the resulting response object will not have duplicate keys:
@@ -1266,7 +1267,7 @@ Type : Name
 
 - Let {name} be the string value of {Name}.
 - Let {type} be the type defined in the Schema named {name}.
-- {type} must not be {null}.
+- {type} must exist.
 - Return {type}.
 
 Type : [ Type ]