Add documentation for codemods

website/docs/guides/alias-directive.md

@@ -105,7 +105,8 @@ We've outlined two different ways that fragments can be unsafe in Relay today wi
 
 To experiment with this validation in your project today, you can enable the experimental `enforce_fragment_alias_where_ambiguous` compiler feature flag for your project. To enable incremental adoption of this enforcement, Relay exposes a directive `@dangerously_unaliased_fixme` which will suppress these enforcement errors. This will allow you to enable the enforcement for all new spreads without first needing to migrate all existing issues.
 
-The [Relay VSCode extension](../editor-support.md) offers quick fixes to add either `@alias` or `@dangerously_unaliased_fixme` to unsafe fragments.
+The [Relay VSCode extension](../editor-support.md) offers quick fixes to add either `@alias` or `@dangerously_unaliased_fixme` to unsafe fragments, and the
+[mark-dangerous-conditional-fragment-spreads](../codemods/#mark-dangerous-conditional-fragment-spreads) codemod can be used to apply `@dangerously_unaliased_fixme` across your entire project.
 
 ## Use with @required
 

website/docs/guides/codemods.md

@@ -0,0 +1,57 @@
+---
+id: codemods
+title: Codemods
+slug: /guides/codemods/
+description: Relay guide to codemods
+keywords:
+  - codemod
+  - codemods
+---
+
+import DocsRating from '@site/src/core/DocsRating'; import {FbInternalOnly,
+OssOnly, fbContent} from 'docusaurus-plugin-internaldocs-fb/internal'; import
+Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem';
+
+The Relay compiler has the ability to make changes across the source files of
+your projects with the use of codemods. You can see the list of codemods
+available by running the Relay compiler's `codemod` command:
+
+```
+> relay codemod --help
+Apply codemod (verification with auto-applied fixes)
+
+Usage: relay codemod [OPTIONS] [CONFIG] <COMMAND>
+
+Commands:
+  mark-dangerous-conditional-fragment-spreads  Marks unaliased conditional fragment spreads as @dangerously_unaliased_fixme
+  help                                         Print this message or the help of the given subcommand(s)
+
+Arguments:
+  [CONFIG]  Compile using this config file. If not provided, searches for a config in package.json under the `relay` key or `relay.config.json` files among other up from the current working directory
+
+Options:
+  -p, --project <project>  Compile only this project. You can pass this argument multiple times. to compile multiple projects. If excluded, all projects will be compiled
+  -h, --help               Print help
+```
+
+## Available codemods
+
+The compiler currently has one available codemod:
+
+### mark-dangerous-conditional-fragment-spreads
+
+This codemod finds fragment spreads that are _dangerously unaliased_; that is,
+the fragment might not be fetched due to a directive such as `@skip` or its
+inclusion on a mismatched type within a union. If such a conditional fragment is
+not aliased with [`@alias`](../alias-directive/), there is no way for the
+resulting generated Flow or TypeScript types to reflect its nullability. This
+codemod will add the `@dangerously_unaliased_fixme` directive to such fragment
+spreads, indicating to developers that there is a problem to be fixed. After
+applying this codemod, the `enforce_fragment_alias_where_ambiguous` feature flag
+can be enabled, which will ensure any future ambiguous fragment spreads must be
+aliased.
+
+Since this codemod can potentially modify many files, there is an optional
+`--rollout` parameter which, if used alongside the
+`enforce_fragment_alias_where_ambiguous` feature flag in rollout mode, allows
+progressive codemod and enforcement of this validation.

website/sidebars.js

@@ -135,6 +135,7 @@ const Guides = {
     }),
     'guides/type-emission',
   ],
+  Codemods: ['guides/codemods'],
   // TODO(T84797602) release incremental data delivery externally
   // 'guides/incremental-data-delivery',
   // TODO release these in OSS