Skip to content

Commit 83348e7

Browse files
authored
Merge pull request #2017 from ahoppen/ahoppen/commit-and-ci-documentation
Add documentation how to author commits, PR reviews and CI
2 parents e42bece + 0f217c6 commit 83348e7

File tree

1 file changed

+15
-1
lines changed

1 file changed

+15
-1
lines changed

CONTRIBUTING.md

Lines changed: 15 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -29,6 +29,20 @@ Generated source code is not formatted to make it easier to spot changes when re
2929

3030
If you want to modify the generated files, open the [CodeGeneration](CodeGeneration) package and run the `generate-swift-syntax` executable.
3131

32+
## Authoring commits
33+
34+
Prefer to squash the commits of your PR (*pull request*) and avoid adding commits like “Address review comments”. This creates a clearer git history, which doesn’t need to record the history of how the PR evolved.
35+
36+
We prefer to not squash commits when merging a PR because, especially for larger PRs, it sometimes makes sense to split the PR into multiple self-contained chunks of changes. For example, a PR might do a refactoring first before adding a new feature or fixing a bug. This separation is useful for two reasons:
37+
- During review, the commits can be reviewed individually, making each review chunk smaller
38+
- In case this PR introduced a bug that is identified later, it is possible to check if it resulted from the refactoring or the actual change, thereby making it easier find the lines that introduce the issue.
39+
40+
## Review and CI Testing
41+
42+
After you opened your PR, a maintainer will review it and test your changes in CI (*Continuous Integration*) by adding a `@swift-ci Please test` comment on the pull request. Once your PR is approved and CI has passed, the maintainer will merge your pull request.
43+
44+
Only contributors with [commit access](https://www.swift.org/contributing/#commit-access) are able to approve pull requests and trigger CI.
45+
3246
## Additional Verification
3347

3448
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.
@@ -51,4 +65,4 @@ When testing finds one of these failures, it will show you the syntax tree that
5165

5266
## Swift Version
5367

54-
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).
68+
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).

0 commit comments

Comments
 (0)