Add migration steps for all deprecations and API-incompatible changes

This should make it easier for clients to migrate to new versions of swift-syntax.

Author: ahoppen

Release Notes/511.md

@@ -24,37 +24,44 @@
   - Description: `is`, `as`, and `cast` methods for types not contained in the choice node are marked as deprecated. The deprecated methods will emit a warning, indicating that the cast will always fail.
   - Issue: https://github.com/apple/swift-syntax/issues/2092
   - Pull Request: https://github.com/apple/swift-syntax/pull/2184
+  - Migration steps: Remove the `is`, `as` or `cast` methods because they will always fail.
 
 - `IncrementalParseTransition`:
   - Description: The initializer `IncrementalParseTransition.init(previousTree:edits:lookaheadRanges:reusedNodeCallback:)` is marked as deprecated. Use `IncrementalParseTransition.init(previousIncrementalParseResult:edits:reusedNodeCallback:)` instead.
   - Issue: https://github.com/apple/swift-syntax/issues/2267
   - Pull request: https://github.com/apple/swift-syntax/pull/2272
+  - Migration steps: Call `IncrementalParseTransition.init(previousIncrementalParseResult:edits:reusedNodeCallback:)` instead.
 
 ## API-Incompatible Changes
 
 - Effect specifiers:
   - Description: The `unexpectedAfterThrowsSpecifier` node of the various effect specifiers has been removed.
   - Pull request: https://github.com/apple/swift-syntax/pull/2219
+  - Migration steps: Check `unexpectedBetweenThrowsSpecifierAndThrownError` and `unexpectedAfterThrownError` instead. 
 
 - `SyntaxKind` removed conformance to `CaseIterable`
   - Description: `SyntaxKind` no longer conforms to `CaseIterable` since there is no good use case to iterate over all syntax kinds. 
-  - Pull request: https://github.com/apple/swift-syntax/pull/2292
+  - Pull request: https://github.com/apple/swift-syntax/pull/2292 
+  - Migration steps: Exhaustively check all the syntax nodes that your program supports. There should be no use case to iterate over all cases in `SyntaxKind`.
 
 - `IntegerLiteralExprSyntax.Radix` removed conformance to `CaseIterable`
   - Description: `IntegerLiteralExprSyntax.Radix` no longer conforms to `CaseIterable` since there is no good use case to iterate over all radix kinds. 
   - Pull request: https://github.com/apple/swift-syntax/pull/2292
+  - Migration steps: There should be no use case to iterate over all cases in `IntegerLiteralExprSyntax.Radix`.
 
 - `Parser.parseIncrementally(source:parseTransition:)` and `Parser.parseIncrementally(source:maximumNestingLevel:parseTransition:)`:
   - Description: The default versions of `Parser.parseIncrementally` return a `IncrementalParseResult` instead of a tuple. Access to the struct should be compatible with the tuple in almost all cases unless the tuple is stored into a variable and then destructed or passed to a function that expects a tuple.
   - Issue: https://github.com/apple/swift-syntax/issues/2267
   - Pull request: https://github.com/apple/swift-syntax/pull/2272
+  - Migration steps: If necessary, change type annotations from the tuple to the `IncrementalParseResult` type.
 
 ## Template
 
 - *Affected API or two word description*
   - Description: *A 1-2 sentence description of the new/modified API*
   - Issue: *If an issue exists for this change, a link to the issue*
   - Pull Request: *Link to the pull request(s) that introduces this change*
+  - Migration steps: Steps that adopters of swift-syntax should take to move to the new API (required for deprecations and API-incompatible changes).
   - Notes: *In case of deprecations or API-incompatible changes, the reason why this change was made and the suggested alternative*
 
 *Insert entries in chronological order, with newer entries at the bottom*