Improve CONTRIBUTING.md

The document was a little bit outdated. I simplified it to focus on the common development workflows that just open swift-syntax as a SwiftPM package, skipping all paths that go through build-script.py, which shouldn’t be necessary for 95% of all contributors, especially newcomers who this document is designed for.

Author: ahoppen

CONTRIBUTING.md

@@ -1,109 +1,54 @@
 # Contributing
 
-This guide refers to Swift Development Snapshots. These can be downloaded from [swift.org/download](https://swift.org/download/#snapshots). 
-If you are seeing issues, it is generally a good idea to re-try with the latest Swift Development Snapshot.
+## Building & Testing
 
-## Building
+swift-syntax is a SwiftPM package, so you can build and test it using anything that supports packages - opening in Xcode, Visual Studio Code with [Swift for Visual Studio Code](https://github.com/swift-server/vscode-swift) installed, or through the command line using `swift build` and `swift test`.
 
-The easiest option to build SwiftSyntax is to open it in Xcode. 
+> 💡 Tip: Running swift-syntax’s self-parse tests takes the majority of testing time. If you want to iterate quickly, you can skip these tests:
+> - In Xcode
+>   1. Product -> Scheme -> Edit Scheme…
+>   2. Select the Arguments tab in the Run section
+>   3. Add a `SKIP_LONG_TESTS` environment variable with value `1`
+> - On the command line: Set the `SKIP_LONG_TESTS` environment variable to `1` when running tests, e.g by running `SKIP_LONG_TESTS=1 swift test`
 
-Alternatively you can also build it from the command line using `build-script.py`. To do this, perform the following steps
-
-1. Check `swift-syntax` and `swift-argument-parser` out side by side:
-     ```
-     - (enclosing directory)
-       - swift-argument-parser
-       - swift-syntax
-     ```
-2. Execute the following command
-    ```bash
-    swift-syntax/build-script.py build --toolchain /Library/Developer/Toolchains/swift-DEVELOPMENT-SNAPSHOT-<recent date>.xctoolchain/usr
-    ```
+> 💡 Tip: If you are only modifying the `SwiftParser` module, you can run only the parser tests by selecting the `SwiftParserTest` target. 
+> - In Xcode: Select the `SwiftParserTest` scheme. If you can’t find it in your Schemes, you need to manually add it using Product -> Scheme -> New Scheme…
+> - On the command line: Run `swift test --test-product SwiftParserTests`
 
 ## Formatting
 
-SwiftSyntax is being formatted using [swift-format](http://github.com/apple/swift-format) to ensure a consistent style.
-
-To format your changes run `format.py` at the root of this repository. If you have a `swift-format` executable ready, you can pass it to `format.py`. If you do not, `format.py` will build its own copy of `swift-format` in /tmp/swift-format.
-
-CI will ensure that all hand-written source code is correctly formatted. Generated source code is not formatted to make it easier to spot changes when re-running code generation.
-
-## Testing
-
-Because of SwiftSyntax’s integration with the Swift compiler project, testing certain parts of the project is a little bit more involved than others. 
-
-The `SwiftParser` tests have no dependencies, other `XCTests` require you to use a matching Swift Development Snapshot, `lit`-based test require a compiler build.
-
-Run the tests that you believe are necessary locally. CI will always run all test before allowing the PR to be merged.
-
-### SwiftParser
+swift-syntax is formatted using [swift-format](http://github.com/apple/swift-format) to ensure a consistent style.
 
-If you are only modifying the `SwiftParser` module, you can just run the tests using Xcode by testing the `SwiftParserTest` target. 
+To format your changes run `format.py` at the root of this repository. If you have a `swift-format` executable ready, you can pass it to `format.py`. If you do not, `format.py` will build its own copy of `swift-format` in `/tmp/swift-format`.
 
-If you can’t find it in your Schemes, you need to manually add it using Product -> Scheme -> New Scheme…
+If you are seeing surprising formatting results, you most likely have a `swift-format` installed on your system that’s not the most recent version built from the `main` branch. To fix this, clone [swift-format](http://github.com/apple/swift-format), build it using `swift build` and pass the freshly built executable to `format.py` as `--swift-format path/to/swift-format/.build/debug/swift-format`. Alternatively, you can uninstall `swift-format` on your system and `format.py` will build it from scratch.
 
-### XCTests
+Generated source code is not formatted to make it easier to spot changes when re-running code generation.
 
-To run the tests in Xcode, select the SwiftSyntax-Package scheme and hit Product -> Test.
-
-You can also run the tests from the command line using
-```bash
-./build-script.py test --toolchain /Library/Developer/Toolchains/swift-DEVELOPMENT-SNAPSHOT-<recent date>.xctoolchain/usr --skip-lit-tests
-```
+## Generating Source Code
 
-If you are seeing issues regarding a mismatched parser library, try the following
-1. Update your Swift Development Snapshot
-2. Revert your swift-syntax checkout to the date of your Swift Development Snapshot
-3. Wait for a new Swift Development Snapshot
-4. If the above options are not possible, build your own Swift toolchain locally and use that toolchain as the `--toolchain` parameter for SwiftSyntax’s `build-script.py` invocations
-  - Note: Building your own toolchain will take more than 1 hour and even longer if you are running into any issues. We do not recommend building your own Swift toolchain unless you are familiar with Swift compiler development.
+If you want to modify the generated files, open the [CodeGeneration](CodeGeneration) package and run the `generate-swift-syntax` executable.
 
-Tip: Running SwiftSyntax’s self-parse tests takes the majority of testing time. If you want to iterate quickly, you can skip these tests using the following steps:
-1. Product -> Scheme -> Edit Scheme…
-2. Select the Arguments tab in the Run section
-3. Add a `SKIP_LONG_TESTS` environment variable with value `1`
+## Additional Verification
 
-### Additional Verification
+swift-syntax has additional verification methods (see the sections below) that provide more extensive validation. They have a significant runtime impact on swift-syntax and are thus not enabled by default when building swift-syntax, but are enabled in CI. If CI fails and you are unable to reproduce the failure locally, make sure that `SKIP_LONG_TESTS` is not set and try enabling these validations.
 
-swift-syntax has two additional verification methods (see the two sections below) that provide more extensive validation. They have significant runtime impact on swift-syntax and are thus not enabled by default when building swift-syntax, but are enabled in CI. If CI fails and you are unable to reproduce the failure locally, make sure that `SKIP_LONG_TESTS` is not set and try enabling these validations.
+### RawSyntax Validation
 
-#### RawSyntax Validation
+When the `SWIFTSYNTAX_ENABLE_RAWSYNTAX_VALIDATION` environment variable is set while building swift-syntax, SwiftSyntax will perform additional validation that the layout of the syntax tree is correct. It validates that 
+1. every child of a syntax node has the correct kind, which should be guaranteed by the Swift type system in most cases
+2. each token only has one of the token kinds that is specified in the syntax tree layout of the `CodeGeneration` package. 
 
-When the `SWIFTSYNTAX_ENABLE_RAWSYNTAX_VALIDATION` environment variable is set while building swift-syntax (or the check for that variable has been changed to always return `true` in Package.swift), SwiftSyntax will perform additional validation that the layout of the syntax tree is correct. It validates that every child of a syntax node has the correct kind (which should be guaranteed by the Swift type system in most cases) and, more importantly, validates that each token only has one of the token kinds that is specified in the syntax tree layout of the `CodeGeneration` package. 
+If this validation hits an assertion failure that a token is not accepted at a certain position in the syntax tree, double-check if the token kind that is being stored in the syntax tree actually makes sense here. If it does not, check if there is a parser bug or whether you need to remap the token kind. If it does make sense, add the token kind to `.token(choices:)` of the syntax node in CodeGeneration, re-generate that source code and run tests again.
 
-If this validation hits an assertion failure that a token is not accepted at a certain position in the syntax tree, double check if the token kind that is being stored in the syntax tree actually makes sense here. If it does not, check if there is a parser bug or whether you need to remap the token kind. If it does make sense, add the token kind to `.token(choices:)` of the syntax node in CodeGeneration, re-generate that source code and run tests again.
+> 💡 Tip: If you want to run tests in Xcode with RawSyntax validation enabled, you can also modify Package.swift and replace the check for `SWIFTSYNTAX_ENABLE_RAWSYNTAX_VALIDATION` with `true`.
 
-#### Test Case Mutation
+### Test Case Mutation
 
-When the `SWIFTPARSER_ENABLE_ALTERNATE_TOKEN_INTROSPECTION` environment variable is set while building swift-syntax (or the check for that variable has been changed to always return `true` in Package.swift), SwiftParser records alternative tokens that the parser was looking for at specific offsets in the source file (e.g. whether it also checked for a `struct` keyword when the source code contained a `class` keyword). It will then use that information to mutate the test case by e.g. substituting `class` by `struct`.
+When the `SWIFTPARSER_ENABLE_ALTERNATE_TOKEN_INTROSPECTION` environment variable is set while building swift-syntax, SwiftParser records alternative tokens that the parser was looking for at specific offsets in the source file, e.g. whether it also checked for a `struct` keyword when the source code contained a `class` keyword. It will then use that information to mutate the test case by e.g. substituting `class` with `struct`.
 
 When testing finds one of these failures, it will show you the syntax tree that produced the failure. Create a new test case with the source code the failure gives you and fix the failure.
 
-### `lit`-based Tests
-
-A few tests are based LLVM’s `lit` and `FileCheck` tools.
-To run these, build `FileCheck`, e.g. by building the Swift compiler and run the tests using the following command:
-```bash
-./build-script.py test --toolchain /Library/Developer/Toolchains/swift-DEVELOPMENT-SNAPSHOT-<recent date>.xctoolchain/usr --filecheck-exec /path/to/build/Release+Asserts/llvm-macosx-x86_64/bin/FileCheck
-```
-
-## Generating Source Code
-
-If you want to modify the code-generated files, perform the following steps:
-
-1. Check out `swift` next to `swift-syntax`
-    ```
-    - (enclosing directory)
-      - swift
-      - swift-argument-parser
-      - swift-syntax
-    ```
-2. Run the following command
-    ```bash
-    swift-syntax/build-script.py generate-source-code --toolchain /Library/Developer/Toolchains/swift-DEVELOPMENT-SNAPSHOT-<recent date>.xctoolchain/usr
-    ```
-3. The new source-generated file will be written into your `Sources` directory.
-
 ## Swift Version
 
-We require that SwiftSyntax builds with the latest released compiler and the previous major version (e.g. with Swift 5.8 and Swift 5.7).
+We require that swift-syntax builds with the latest released compiler and the previous major version (e.g. with Swift 5.8 and Swift 5.7).