Changesets and doc updates

Author: emmatown

.changeset/cool-oranges-tease.md

@@ -0,0 +1,5 @@
+---
+"@graphql-ts/extend": patch
+---
+
+Documentation updates to align with the renaming of the `graphql` export to `g` in `@graphql-ts/schema`

.changeset/nasty-turkeys-destroy.md

@@ -0,0 +1,15 @@
+---
+"@graphql-ts/schema": patch
+---
+
+The `graphql` export has been renamed to `g` to make reading/writing schemas more concise and to avoid conflicts with exports named `graphql` from libraries such as Relay, GraphQL Code Generator and gql.tada that use the variable name `graphql` to declare GraphQL operations.
+
+The `graphql` export still exists but is now deprecated and may be removed in a future release.
+
+To quickly update usages of the `graphql` export in your project to use `g`:
+
+1. Navigate to `node_modules/@graphql-ts/schema/dist/declarations/src/schema-api-alias.d.ts` in your editor ("Go to Definition" will not take you to the correct file)
+2. Use "Rename Symbol" to rename `graphql` to `g`, this will update usages of `graphql` to `g`
+3. Change this deprecated alias back from `g` to `graphql` (avoid using "Rename Symbol" again because you want to preserve the updates you made in step 2)
+
+You can similarly use "Rename Symbol" to quickly rename your own custom defined `graphql` to `g`.

packages/schema/src/schema-api-alias.d.ts

@@ -1,18 +1,28 @@
+import * as _graphql from "./schema-api";
+
 /**
  * The `graphql` export has been renamed to `g`.
  *
  * To quickly update usages of `graphql` in your project to `g`:
  *
- * 1. Use your editor's "Go to Definition" to go navigate to where this deprecated
- *    alias is defined
+ * 1. Navigate to
+ *    `node_modules/@graphql-ts/schema/dist/declarations/src/schema-api-alias.d.ts`
+ *    in your editor ("Go to Definition" will not take you to the correct file)
  * 2. Use "Rename Symbol" to rename `graphql` to `g`, this will update usages of
  *    `graphql` to `g`
  * 3. Change this deprecated alias back from `g` to `graphql` using normal text
- *    editing to preserve the updates you made in step 2
+ *    editing (avoid using "Rename Symbol" again because you want to preserve
+ *    the updates you made in step 2)
  *
- * You can similarly use "Rename Symbol" to quickly rename your own custom
- * defined `graphql` to `g` if you wish.
+ * You can also use "Rename Symbol" to quickly rename your own custom defined
+ * `graphql` export to `g`.
  *
  * @deprecated
  */
-export import graphql = require("./schema-api");
+// this is what you should run "Rename Symbol" on
+// when that is done, you should change it back to `export import graphql = _graphql;`
+// avoid using "Rename Symbol" to revert it because you want to
+// preserve the updates you made to the usages of `graphql`
+//            |||||||
+//            vvvvvvv
+export import graphql = _graphql;