Complete Migration Guide and Project Configuration Documentation (#2698)

Co-authored-by: Calvin Cestari <[email protected]>

Sources/ApolloCodegenLib/ApolloCodegenConfiguration.swift

@@ -286,7 +286,7 @@ public struct ApolloCodegenConfiguration: Codable, Equatable {
     /// Generated test mock files will be located in the specified path.
     /// No module will be created for the generated test mocks.
     ///
-    ///- Note: Generated files must be manually added to your test target. Test mocks generated
+    /// - Note: Generated files must be manually added to your test target. Test mocks generated
     /// this way may also be manually embedded in a test utility module that is imported by your
     /// test target.
     case absolute(path: String)

Tests/TestCodeGenConfigurations/EmbeddedInTarget-InSchemaModule/Package.resolved

@@ -23,8 +23,8 @@
       "kind" : "remoteSourceControl",
       "location" : "https://github.com/apple/swift-argument-parser.git",
       "state" : {
-        "revision" : "9f39744e025c7d377987f30b03770805dcb0bcd1",
-        "version" : "1.1.4"
+        "revision" : "fddd1c00396eed152c45a46bea9f47b98e59301d",
+        "version" : "1.2.0"
       }
     },
     {

docs/.vscode/settings.json

@@ -0,0 +1,3 @@
+{
+    "markdown.extension.toc.updateOnSave": false
+}

docs/shared/cli-install/pods.mdx

@@ -0,0 +1,7 @@
+When using Cocoapods, Apollo iOS compiles the Codegen CLI into an executable shell application during `pod install`, which is located in your project at `Pods/Apollo/apollo-ios-cli`.
+
+After installing the Apollo iOS pod, you can run the Codegen CLI from the directory of your `Podfile`:
+
+```bash
+./Pods/Apollo/apollo-ios-cli ${Command Name} -${Command Arguments}
+```

docs/shared/spm-install-cli.mdx → docs/shared/cli-install/spm-xcode.mdx

@@ -4,15 +4,9 @@ To simplify accessing the Codegen CLI, you can run the included `InstallCLI` SPM
 
 This plugin builds the CLI and creates a symbolic link to the executable in your project root.
 
-When using a `Package.swift` file, install the CLI by running:
-
-```bash
-swift package --allow-writing-to-package-directory apollo-cli-install
-```
-
 When using Swift packages through Xcode, right-click on your project in the Xcode file explorer and at the bottom of the menu you will find the `InstallCLI` plugin command. Clicking on this will present a dialog asking for permission for the plugin to write to your project directory.
 
-<img class="screenshot" src="../source/screenshot/apollo-xcode-plugin.png" alt="Where to find the SPM plugin commands in Xcode" />
+<img class="screenshot" src="../../source/screenshot/apollo-xcode-plugin.png" alt="Where to find the SPM plugin commands in Xcode" />
 
 After running the installation plugin, a symbolic link to the Codegen CLI named `apollo-ios-cli` is located in your project root folder. You can now run the CLI from the command line with `./apollo-ios-cli`.
 

docs/shared/cli-install/spm.mdx

@@ -0,0 +1,15 @@
+The Apollo iOS SPM package includes the Codegen CLI as an executable target. This ensures you always have a valid CLI version for your Apollo iOS version.
+
+To simplify accessing the Codegen CLI, you can run the included `apollo-cli-install` SPM plugin.
+
+This plugin builds the CLI and creates a symbolic link to the executable in your project root.
+
+When using a `Package.swift` file, install the CLI by running:
+
+```bash
+swift package --allow-writing-to-package-directory apollo-cli-install
+```
+
+After running the installation plugin, a symbolic link to the Codegen CLI named `apollo-ios-cli` is located in your project root folder. You can now run the CLI from the command line with `./apollo-ios-cli`.
+
+> **Note:** Because the `apollo-ios-cli` in your project root is only a symbolic link, it will only work if the compiled CLI exectuable exists. This is generally located in your Xcode Derived Data or the `.build` folder. If these are cleared, you can run the install plugin again to re-build the CLI executable.

docs/shared/separate-local-cache-mutation-note.mdx

@@ -0,0 +1,7 @@
+> #### Separating Cache Mutations from Network Operations
+>
+> The generated models for queries defined as cache mutations will conform to `LocalCacheMutation`, but not `GraphQLQuery`. This means they cannot be sent as query operations to your server using an `ApolloClient`. Because network response data is immutable and cache mutation models are mutable, you must use separate models.
+>
+> Because mutable data requires a lot more generated code, generating mutable models for all operations would nearly double the size of the generated operations. Additionally, if the models were mutable, mutating them outside of a `ReadWriteTransaction` would not persist any changes to the cache. By maintaining immutable models, we avoid any confusion this could cause.
+>
+> Cache mutations are designed to be narrowly scoped to access and mutate only the necessary data. You should avoid creating mutable versions of entire query operations. Instead, define mutable fragments or queries to mutate only the necessary fields.

docs/shared/setup-codegen/combined.mdx

@@ -0,0 +1,25 @@
+import SPMInstallCLI from "../cli-install/spm.mdx"
+import SPMXcodeInstallCLI from "../cli-install/spm-xcode.mdx"
+import PodsInstallCLI from "../cli-install/pods.mdx"
+import SetupCodegenPanel from "./single-panel.mdx"
+
+<a name="spm-setup-codegen" />
+<ExpansionPanel title="SPM with Package.swift">
+
+<SetupCodegenPanel cliPath="./apollo-ios-cli" moduleTypeOption="`.swiftPackageManager`" installComponent={<SPMInstallCLI />} />
+
+</ExpansionPanel>
+
+<a name="spm-xcode-setup-codegen" />
+<ExpansionPanel title="SPM with Xcode Project">
+
+<SetupCodegenPanel cliPath="./apollo-ios-cli" moduleTypeOption="`.swiftPackageManager`" installComponent={<SPMXcodeInstallCLI />} />
+
+</ExpansionPanel>
+
+<a name="pods-setup-codegen" />
+<ExpansionPanel title="Cocoapods">
+
+<SetupCodegenPanel cliPath="./Pods/Apollo/apollo-ios-cli" moduleTypeOption="`.other`" installComponent={<PodsInstallCLI />} />
+
+</ExpansionPanel>

docs/shared/spm-setup-codegen-panel.mdx → docs/shared/setup-codegen/single-panel.mdx

@@ -1,29 +1,35 @@
-import SPMInstallCLI from "../shared/spm-install-cli.mdx"
-
-<ExpansionPanel title="Swift Package Manager">
+import {CodeBlock, CodeBlockProps} from "@apollo/chakra-helpers"
 
 <ExpansionPanelList>
 
 <ExpansionPanelListItem>
 
 #### Install the Codegen CLI
 
-<SPMInstallCLI />
+<>{props.installComponent}</>
 
 </ExpansionPanelListItem>
 
 <ExpansionPanelListItem>
 
 #### Initialize the code generation configuration
 
-The Codegen CLI uses a JSON file to configure the code generation engine. Use the Codegen CLI `init` command to create this file with default values. From your project's root directory, run:
+The Codegen CLI uses a JSON file to configure the code generation engine. Use the Codegen CLI `init` command to create this file with default values.
+
+From your project's root directory, run:
 
-```bash
-./apollo-ios-cli init --schema-name ${MySchemaName} --module-type swiftPackageManager
-```
+<CodeBlock
+  code={props.cliPath + " init --schema-name ${MySchemaName} --module-type ${ModuleType}"}
+  language="bash"
+  showLineNumbers='true'
+/>
 
-* `${MySchemaName}` should be the name you want for the namespace of your generated schema files.
-* `embeddedInTarget` or `swiftPackageManager` are both suitable module types to use when your dependency manager for Apollo iOS is Swift Package Manager.
+- `${MySchemaName}` should be the name you want for the namespace of your generated schema files.
+- `${ModuleType}` is used to configure how your generated schema types will be included in your project.
+  > This is an important decision that must be made prior to configuring code generation. To determine the right option for your project, check our our [project configuration documentation](/project-configuration).
+  >
+  > To get started quickly, you can use the `.embeddedInTarget` option.
+  > If you use this option you will need to also supply a target name using the `--target-name` command line option.
 
 This will create an `apollo-codegen-config.json` file with the default values.
 
@@ -38,7 +44,7 @@ The default configuration will:
 - Find all GraphQL schema files ending with the file extension `.graphqls` within your project directory.
 - Find all GraphQL operation and fragment definition files ending with the file extension `.graphql` within your project directory.
 - Generate Swift code for the schema types in a directory with the `schema-name` provided.
-- Generate Swift code for the operation and fragment models relative to the `.graphql` files that define them.
+- Generate Swift code for the operation and fragment models in a subfolder within the schema types output location.
 
 </ExpansionPanelListItem>
 <ExpansionPanelListItem>
@@ -47,9 +53,11 @@ The default configuration will:
 
 From your project's root directory, run:
 
-```bash
-./apollo-ios-cli generate
-```
+<CodeBlock
+  code={props.cliPath + " generate"}
+  language="bash"
+  showLineNumbers='true'
+/>
 
 Your generated files will be created with the file extension `.graphql.swift`.
 
@@ -58,12 +66,11 @@ Your generated files will be created with the file extension `.graphql.swift`.
 
 #### Add the generated schema and operation files to your target
 
-By default, a directory containing your generated schema files will be located in a directory with the `schema-name` you provided; your generated operation and fragment files will be in the same location as the `.graphql` files they are defined by.
+By default, a directory containing your generated schema files will be located in a directory with the `schema-name` you provided; your generated operation and fragment files will be in a subfolder in that same directory.
 
 If your target is created in an Xcode project or workspace, you will need to manually add the generated files to your target.
 
-> **Note:** Because adding generated files to your Xcode targets must be done manually each time you generate new files, we highly recommend defining your project targets with SPM. Alternatively, you can generate your operations into the package that includes your schema files. For more information see the documentation for [Code Generation Configuration](./codegen-configuration).
+> **Note:** Because adding generated files to your Xcode targets must be done manually each time you generate new files, we highly recommend defining your project targets with SPM. Alternatively, you can generate your operations into the package that includes your schema files. For more information see the documentation for [Code Generation Configuration](./../../code-generation/codegen-configuration).
 
 </ExpansionPanelListItem>
 </ExpansionPanelList>
-</ExpansionPanel>

docs/shared/spm-package-installation-panel.mdx

@@ -9,7 +9,10 @@ If your project uses its own `Package.swift` file, you can add Apollo iOS as a d
 
 ```swift title="Package.swift"
 dependencies: [
-    .package(url: "https://github.com/apollographql/apollo-ios.git", .upToNextMajor(from: "1.0.0")),
+    .package(
+        url: "https://github.com/apollographql/apollo-ios.git",
+        .upToNextMajor(from: "1.0.0")
+    ),
 ],
 ```
 

docs/source/caching/cache-transactions.mdx

@@ -2,6 +2,8 @@
 title: Direct cache access
 ---
 
+import SeparateLocalCacheMutationsNote from "../../shared/separate-local-cache-mutation-note.mdx"
+
 Apollo iOS provides the ability to directly read and update the cache as needed using type-safe generated operation models. This provides a strongly-typed interface for accessing your cache data in pure Swift code.
 
 The `ApolloStore` has APIs for accessing the cache via both `ReadTransaction` and `ReadWriteTransaction`.
@@ -73,13 +75,7 @@ fragment MutableHeroDetails on Hero
 
 The generated models for your mutations will have mutable fields (`var` instead of `let`). Generating both getters and setters for fields on the mutable models means that they are larger than immutable generated models.
 
-> #### Seperating Cache Mutations from Network Operations
->
-> The generated models for queries defined as cache mutations will conform to `LocalCacheMutation`, but not `GraphQLQuery`. This means they cannot be sent as query operations to your server using an `ApolloClient`. Because network response data is immutable and cache mutation models are mutable, you must use seperate models.
->
-> Because mutable data requires a lot more generated code, generating mutable models for all operations would nearly double the size of the generated operations. Additionally, if the models were mutable, mutating them outside of a `ReadWriteTransaction` would not persist any changes to the cache. By maintaining immutable models, we avoid any confusion this could cause.
->
-> Cache mutations are designed to be narrowly scoped to access and mutate only the necessary data. You should avoid creating mutable versions of entire query operations. Instead, define mutable fragments or queries to mutate only the necessary fields.
+<SeparateLocalCacheMutationsNote />
 
 ### Writing local cache mutations to the cache
 

docs/source/code-generation/codegen-cli.mdx

@@ -2,7 +2,9 @@
 title: The Codegen CLI
 ---
 
-import SPMInstallCLI from "../../shared/spm-install-cli.mdx"
+import SPMInstallCLI from "../../shared/cli-install/spm.mdx"
+import SPMXcodeInstallCLI from "../../shared/cli-install/spm-xcode.mdx"
+import PodsInstallCLI from "../../shared/cli-install/pods.mdx"
 
 The Codegen CLI provides a command line tool that streamlines the process of running code generation. The CLI can be ran manually from Terminal (or any other shell program) or can be called into from bash scripts.
 
@@ -21,21 +23,21 @@ When Apollo iOS is included as a dependency through Swift Package Manager (SPM)
 
 To learn how to run the Codegen CLI with your chosen package manager, open the appropriate section:
 
-<ExpansionPanel title="Swift Package Manager - Xcode">
+<ExpansionPanel title="SPM with Package.swift">
 
 <SPMInstallCLI />
 
 </ExpansionPanel>
 
-<ExpansionPanel title="CocoaPods">
+<ExpansionPanel title="SPM with Xcode Project">
 
-When using Cocoapods, Apollo iOS compiles the Codegen CLI into an executable shell application during `pod install`, which is located in your project at `Pods/Apollo/apollo-ios-cli`.
+<SPMXcodeInstallCLI />
 
-After installing the Apollo iOS pod, you can run the Codegen CLI from the directory of your `Podfile`:
+</ExpansionPanel>
 
-```bash
-./Pods/Apollo/apollo-ios-cli ${Command Name} -${Command Arguments}
-```
+<ExpansionPanel title="Cocoapods">
+
+<PodsInstallCLI />
 
 </ExpansionPanel>
 

docs/source/code-generation/codegen-configuration.mdx

@@ -148,7 +148,7 @@ The properties to configure `output.schemaTypes` are:
 | Property Name | Description |
 | ------------- | ----------- |
 | `path` | A file path where the generated schema types should be output.<br/><br/>Relative to your project root |
-| [`moduleType`](#moduleType) | How generated schema types will be linked to your project. |
+| [`moduleType`](#module-type) | How generated schema types will be linked to your project. |
 
 #### Module type
 
@@ -166,21 +166,21 @@ The possible values for `moduleType` are:
 
 | Value | Description |
 | ----- | ----------- |
-| [`embeddedInTarget(name:)`](#embedded-in-target) | Indicates that you would like to include the generated models directly in your application target. |
+| [`embeddedInTarget(name:)`](#embedded-in-target) | Indicates that you would like to include the generated module directly in your application target. |
 | [`swiftPackageManager`](#swift-package-manager)  | Creates a schema module as an SPM package that can be included in your project. |
-| [`other`](#other-schema-module-types) 		   | Indicates that you would like to define a schema module using manually. |
+| [`other`](#other-schema-module-types) 		   | Indicates that you would like to manually define a schema module using a third party package manager (such as Cocoapods). |
 
 #### Embedded in target
 
 **`ModuleType.embeddedInTarget(name: String)`**
 
-This option indicates that you would like to include the generated models directly in your application target.
+This option indicates that you would like to include the generated module directly in your application target.
 
 The `name` parameter must specify the name of the target the schema types will be included in. This will be used to generate `import` statements for generated operations.
 
 No module will be created for the schema types. Instead, generated schema types will be enclosed in a [caseless namespace `enum`](https://www.swiftbysundell.com/articles/powerful-ways-to-use-swift-enums/#namespaces-and-non-initializable-types).
 
-When creating a single target application, this option allows you to include Apollo iOS's generated models directly in your application target.
+When creating a single target application, this option allows you to include Apollo iOS's generated module directly in your application target.
 
 > **Note:** When using this `moduleType`, you are responsible for ensuring the generated files are linked to your application target.
 

docs/source/config.json

@@ -7,6 +7,8 @@
   "sidebar": {
     "Introduction": "/",
     "Get Started": "/get-started",
+    "Migrating to v1.0": "/migrations/1.0",
+    "Project Configuration": "/project-configuration",
     "Tutorial": {
       "Code Generation": "/tutorial/codegen-getting-started"
     },