Add descriptions to executable definitions

[IvanGoncharov]

Was already discussed during WG: https://github.com/graphql/graphql-wg/blob/main/notes/2021-04-01.md#adding-descriptions-to-queries-and-fragments-ivan

I prepare a format proposal, here is a couple of key points:

1. You can add descriptions on operations, fragments, and query variables
2. You can't add description on the short form of operation only full form.

Example:

"Some description"
query SomeOperation(
  "ID you should provide"
  $id: String
  
  "Switch for experiment ...."
  $enableBaz: Boolean = false,
) {
  foo(id: $id) {
    bar
    baz @include(if: $enableBaz) {
      ...BazInfo
    }
  }
}

"Some description here"
fragment BazInfo on Baz {
  # ...
}

[netlify]

✔️ Deploy Preview for graphql-spec-draft ready!

🔨 Explore the source changes: 14cce61

🔍 Inspect the deploy log: https://app.netlify.com/sites/graphql-spec-draft/deploys/615f262e5946770008f041ee

😎 Browse the preview: https://deploy-preview-892--graphql-spec-draft.netlify.app/draft

[IvanGoncharov]

It's an incomplete PR at the moment:

• Need to expand "Descriptions" in Section 2
• Need to figure out what to do with duplicating "Descriptions" in Section 3

[IvanGoncharov]

Capturing feedback from WG (suggested by @fotoetienne):
Add a note that descriptions on executable definitions or comments (retroactive change) must not change execution, validation, or response of graphql document. And it is safe to remove comments and descriptions from executable documents.

[IvanGoncharov]

Implemented in graphql/graphql-js#3402

[leebyron]

@fotoetienne is volunteering to champion this RFC, and we agreed to move this to Draft RFC 2