Development workflow

The Swift project uses a small-incremental-change model on top of GitHub PRs. This page covers the mechanics from "I have an idea" to "my change is on main".

Branches

The repo follows the conventions in docs/Branches.md:

• main -- always the next release.
• release/x.y -- release branches, only fixes get cherry-picked here.
• stable/* -- long-lived stability branches for shipping toolchains.

A bot (automerger -- see docs/Branches.md) keeps release/* synced with main for cherry-picked fixes.

Authoring a change

The canonical small-PR rules are in CONTRIBUTING.md:

• Prefer many small PRs over one large one.
• Each commit should pass tests on its own.
• Keep formatting changes separate from semantic changes.

Commit message format

CONTRIBUTING.md doesn't enforce a strict format but recommends:

Subject (≤72 chars, present tense)

Optional body explaining why the change is needed.

Trailers if any (e.g., rdar://, github issue link).

The repo uses GitHub's "squash and merge" workflow on most PRs.

Opening a pull request

1. Push your branch to a fork.
2. Open a PR against apple/swift:main.
3. Fill the PR description: what, why, links to forum threads / Swift Evolution proposals if applicable.
4. Tag a code owner from CODE_OWNERS.TXT if you know who should review.

CI: @swift_ci

After a code owner approves, comment one of these on the PR:

• @swift_ci please test -- run the standard test matrix.
• @swift_ci please smoke test -- a quick smoke run.
• @swift_ci please test source compatibility -- run the source compatibility suite against your change.
• @swift_ci please clean test -- a clean rebuild, used after merges from main.

See docs/ContinuousIntegration.md for the full list, including platform-specific subsets.

Bisecting a regression

The repo has a bisect helper in utils/bug_reducer/ that wraps git bisect to also bisect within compilation: it can shrink a SIL test case that triggers a crash. The classic flow:

cd ../build/Ninja-RelWithDebInfoAssert/swift-macosx-arm64
git -C ../../../swift bisect start
git -C ../../../swift bisect bad <bad-sha>
git -C ../../../swift bisect good <good-sha>
git -C ../../../swift bisect run ./bin/swiftc -frontend -emit-sil ../../../swift/path/to/repro.swift

For SIL pass-level bisection, see utils/bug_reducer/sil-passpipeline-dumper.py.

Pre-commit checks

The build system runs lint and formatting checks:

• C++ uses clang-format, governed by .clang-format and .clang-tidy.
• Python is checked with flake8 (.flake8) and pylint (utils/python_lint.py).
• utils/git-clang-format-all.zsh runs clang-format over the whole tree.

The CI bots reject PRs that fail formatting. Run:

./utils/git-clang-format-all.zsh
./utils/python_lint.py

before pushing.

After landing

• The change is squashed onto main.
• The release manager may cherry-pick it to release/*.
• Snapshot toolchains pick up the change within a day; check the swift-DEVELOPMENT-SNAPSHOT-* tags.