Add graphql operation naming and organization docs

Reviewed By: captbaritone

Differential Revision: D50636461

fbshipit-source-id: 0e47f3fe926115d030a3fef104c69106d4f1b07b

Author: alichtman

website/docs/tutorial/mutations-updates.md

@@ -142,6 +142,7 @@ const StoryLikeButtonLikeMutation = graphql`
 
 This is a lot, let’s break it down:
 
+* The mutation is named `StoryLikeButton` + `Like` + `Mutation` because it must begin with the module name, and end with the GraphQL operation.
 * The mutation declares <span className="color1">variables</span> which are passed from the client to the server when the mutation is dispatched. Each variable has a name (`$id`, `$doesLike`) and a type (`ID!`, `Boolean!`). The `!` after the type indicates that it is required, not optional.
 * The mutation selects a <span className="color2">mutation field</span> defined by the GraphQL schema. Each mutation field that the server defines corresponds to some action that the client can request of the server, such as liking a story.
     * The <span className="color3">mutation field takes arguments</span> (just like any field can do). Here we pass in the mutation variables that we declared as the argument values — for example, the `doesLike` field argument is set to be the `$doesLike` mutation variable.

website/docs/tutorial/organizing-mutations-queries-and-subscriptions.md

@@ -0,0 +1,24 @@
+## Organizing Mutations, Queries, and Subscriptions
+
+Relay Operations (Mutations, Queries, and Subscriptions) have strict naming requirements. The operation name must begin with the module name, and end with the GraphQL operation type. The name also must be globally unique.
+
+> Sidenote: This naming scheme originates from trying to enforce the uniqueness constraint. At Meta, Haste (a dependency management system for static resources) enforces that all module names are unique to derive sensible globally unique Relay names. Coupling the module name and Relay name also makes it easier to locate a fragment/query/mutation if you know that name. This makes sense within Meta, and may be less sensible in an OSS setting.
+
+For example:
+
+1. A Mutation in the file `MyComponent.js` must be named with the scheme `MyComponent[MyDescriptiveNameHere]Mutation`.
+2. A Query in the file `MyComponent.react.js` must be named with the scheme `MyComponent*Query`.
+
+A NewsFeed component may have mutations/queries that shouldn't logically start with `NewsFeed`, but Relay requires this _if they are defined in that file_.
+
+### Recommended Structure For Mutations and Subscriptions
+
+Put Mutations in their own hook module so the name is closer to _what the mutation does_ rather than _which component invokes it_. If the module name is correctly descriptive, it is fine to declare it in the same file.
+
+If you are adding a Mutation for `Post`, like adding a comment to a post, you may create a new file titled `useAddPostComment.js`. Your mutation (in this file) will then be named `useAddPostCommentMutation`, which is a perfectly descriptive name.
+
+You may consider putting all of these hooks in a dedicated `hooks` directory.
+
+### Recommended Structure for Queries
+
+Root components should have a single query that is tightly coupled to a component, since it describes that component's data dependencies. Queries and fragments should co-locate with their data-use code.

website/docs/tutorial/queries-1.md

@@ -70,7 +70,7 @@ const NewsfeedQuery = graphql`
 Let’s break this down:
 
 * To embed GraphQL within Javascript, we put a string literal <span class="color1">marked with the <code>graphql``</code> tag</span>. This tag allows the Relay compiler to find and compile the GraphQL within a Javascript codebase.
-* Our GraphQL string consists of a <span class="color2">query declaration</span> with the keyword `query` and then a query name.
+* Our GraphQL string consists of a <span class="color2">query declaration</span> with the keyword `query` and then a query name. Note that the query name **must** begin with the module name (in this case <code>Newsfeed</code>).
 * Inside the query declaration are *fields*, which specify what information to query for*:*
     * Some fields are *<span class="color3">scalar fields</span>* that retrieve a string, number, or other unit of information.
     * Other fields are *<span class="color4">edges</span>* that let us traverse from one node in the graph to another. When a field is an edge, it’s followed by another block `{ }` containing fields for the node at the other end of the edge. Here, the `poster` field is an edge that goes from a Story to a Person who posted it. Once we’ve traversed to the Person, we can include fields about the Person such as their `name`.

website/sidebars.js

@@ -138,6 +138,7 @@ module.exports = {
         'tutorial/refetchable-fragments',
         'tutorial/connections-pagination',
         'tutorial/mutations-updates',
+        'tutorial/organizing-mutations-queries-and-subscriptions',
       ],
       Installation: [
         'getting-started/prerequisites',