{"id":11439953,"url":"https://github.com/swiftlang/swift-source-compat-suite","last_synced_at":"2025-05-15T15:08:23.955Z","repository":{"id":20245532,"uuid":"78574614","full_name":"swiftlang/swift-source-compat-suite","owner":"swiftlang","description":"The infrastructure and project index comprising the Swift source compatibility suite.","archived":false,"fork":false,"pushed_at":"2025-05-06T19:52:30.000Z","size":2009,"stargazers_count":286,"open_issues_count":8,"forks_count":153,"subscribers_count":129,"default_branch":"main","last_synced_at":"2025-05-06T20:38:46.588Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/swiftlang.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":"CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2017-01-10T21:15:01.000Z","updated_at":"2025-04-23T06:45:39.000Z","dependencies_parsed_at":"2023-12-14T01:46:13.815Z","dependency_job_id":"862d8a9c-463f-4977-a27f-c8c441b57ca5","html_url":"https://github.com/swiftlang/swift-source-compat-suite","commit_stats":{"total_commits":1308,"total_committers":158,"mean_commits":8.278481012658228,"dds":0.8425076452599388,"last_synced_commit":"b8af801f4508ee7adc3488dffe9956ea4e8e55ff"},"previous_names":["swiftlang/swift-source-compat-suite","apple/swift-source-compat-suite"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/swiftlang%2Fswift-source-compat-suite","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/swiftlang%2Fswift-source-compat-suite/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/swiftlang%2Fswift-source-compat-suite/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/swiftlang%2Fswift-source-compat-suite/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/swiftlang","download_url":"https://codeload.github.com/swiftlang/swift-source-compat-suite/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254364270,"owners_count":22058878,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-06-20T16:08:52.085Z","updated_at":"2025-05-15T15:08:18.945Z","avatar_url":"https://github.com/swiftlang.png","language":"Python","funding_links":[],"categories":["Python","HarmonyOS"],"sub_categories":["Windows Manager"],"readme":"# Swift Source Compatibility Suite\n\nSource compatibility is a strong goal for future Swift releases. To aid in this\ngoal, a community owned source compatibility test suite serves to regression\ntest changes to the compiler against a (gradually increasing) corpus of Swift\nsource code. Projects added to this test suite are periodically built against\nthe latest development versions of Swift as part of [Swift's continuous\nintegration system](https://ci.swift.org), allowing Swift compiler developers to\nunderstand the compatibility impact their changes have on real-world Swift\nprojects.\n\n## Python Support\nThe Source compatibility suite currently supports Python 3.8+. You may experience performance issues if you attempt to execute any of the associated files with a lesser version of Python 3.\n\n## Current List of Projects\n\nThe \u003ca href=\"https://swift.org/source-compatibility/#current-list-of-projects\"\u003ecurrent list of projects\u003c/a\u003e can be viewed on Swift.org.\n\n## Adding Projects\n\nThe Swift source compatibility test suite is community driven, meaning that open\nsource Swift project owners are encouraged to submit their projects that meet\nthe acceptance criteria for inclusion in the test suite. Projects added to the\nsuite serve as general source compatibility tests and are afforded greater\nprotection against unintentional source breakage in future Swift releases.\n\n### Acceptance Criteria\n\nTo be accepted into the Swift source compatibility test suite, a project must:\n\n1. Target Linux, macOS, or iOS/tvOS/watchOS device\n2. Be an *Xcode* or *Swift Package Manager* project (Carthage and CocoaPods are currently unsupported but are being explored to be supported in the future)\n3. Support building on either Linux or macOS\n4. Be contained in a publicly accessible git repository\n5. Maintain a project branch that builds against Swift 4.2 compatibility mode\n   and passes any unit tests\n6. Have maintainers who will commit to resolve issues in a timely manner\n7. Be compatible with the latest GM/Beta versions of *Xcode* and *swiftpm*\n8. Add value not already included in the suite\n9. Be licensed with one of the following permissive licenses:\n\t* BSD\n\t* MIT\n\t* Apache License, version 2.0\n\t* Eclipse Public License\n\t* Mozilla Public License (MPL) 1.1\n\t* MPL 2.0\n\t* CDDL\n\n\n### Adding a Project\n\nTo add a project meeting the acceptance criteria to the suite, perform the\nfollowing steps:\n\n1. Ensure the project builds successfully at a chosen commit against\n   Swift 4.2 GM\n2. Create a pull request against the [source compatibility suite\n   repository](https://github.com/apple/swift-source-compat-suite),\n   modifying **projects.json** to include a reference to the project being added\n   to the test suite.\n\nThe project index is a JSON file that contains a list of repositories containing\nXcode and/or Swift Package Manager target actions.\n\nTo add a new Swift Package Manager project, use the following template:\n\n~~~json\n{\n  \"repository\": \"Git\",\n  \"url\": \"https://github.com/example/project.git\",\n  \"path\": \"project\",\n  \"branch\": \"master\",\n  \"maintainer\": \"email@example.com\",\n  \"compatibility\": [\n    {\n      \"version\": \"4.2\",\n      \"commit\": \"195cd8cde2bb717242b3081f9c367ccd0a2f0121\"\n    }\n  ],\n  \"platforms\": [\n    \"Darwin\"\n  ],\n  \"actions\": [\n    {\n      \"action\": \"BuildSwiftPackage\",\n      \"configuration\": \"release\"\n    },\n    {\n      \"action\": \"TestSwiftPackage\"\n    }\n  ]\n}\n~~~\n\nThe `compatibility` field contains a list of version dictionaries, each\ncontaining a Swift version and a commit. Commits are checked out before\nbuilding a project in the associated Swift version compatibility mode. The\nSwift version is the earliest version of Swift known to compile the project at\nthe given commit. The goal is to have multiple commits at different points in a\nproject's history that are compatible with all supported Swift version\ncompatibility modes.\n\nThe `platforms` field specifies the platforms that can be used to build the\nproject. Linux and Darwin can currently be specified.\n\nIf tests aren't supported, remove the test action entry.\n\nTo add a new Swift Xcode workspace, use the following template:\n\n~~~json\n{\n  \"repository\": \"Git\",\n  \"url\": \"https://github.com/example/project.git\",\n  \"path\": \"project\",\n  \"branch\": \"master\",\n  \"maintainer\": \"email@example.com\",\n  \"compatibility\": [\n    {\n      \"version\": \"4.2\",\n      \"commit\": \"195cd8cde2bb717242b3081f9c367ccd0a2f0121\"\n    }\n  ],\n  \"platforms\": [\n    \"Darwin\"\n  ],\n  \"actions\": [\n    {\n      \"action\": \"BuildXcodeWorkspaceScheme\",\n      \"workspace\": \"project.xcworkspace\",\n      \"scheme\": \"project OSX\",\n      \"destination\": \"platform=macOS\",\n      \"configuration\": \"Release\"\n    },\n    {\n      \"action\": \"BuildXcodeWorkspaceScheme\",\n      \"workspace\": \"project.xcworkspace\",\n      \"scheme\": \"project iOS\",\n      \"destination\": \"generic/platform=iOS\",\n      \"configuration\": \"Release\"\n    },\n    {\n      \"action\": \"BuildXcodeWorkspaceScheme\",\n      \"workspace\": \"project.xcworkspace\",\n      \"scheme\": \"project tvOS\",\n      \"destination\": \"generic/platform=tvOS\",\n      \"configuration\": \"Release\"\n    },\n    {\n      \"action\": \"BuildXcodeWorkspaceScheme\",\n      \"workspace\": \"project.xcworkspace\",\n      \"scheme\": \"project watchOS\",\n      \"destination\": \"generic/platform=watchOS\",\n      \"configuration\": \"Release\"\n    },\n    {\n      \"action\": \"TestXcodeWorkspaceScheme\",\n      \"workspace\": \"project.xcworkspace\",\n      \"scheme\": \"project OSX\",\n      \"destination\": \"platform=macOS\"\n    },\n    {\n      \"action\": \"TestXcodeWorkspaceScheme\",\n      \"workspace\": \"project.xcworkspace\",\n      \"scheme\": \"project iOS\",\n      \"destination\": \"platform=iOS Simulator,name=iPhone 7\"\n    },\n    {\n      \"action\": \"TestXcodeWorkspaceScheme\",\n      \"workspace\": \"project.xcworkspace\",\n      \"scheme\": \"project tvOS\",\n      \"destination\": \"platform=tvOS Simulator,name=Apple TV 1080p\"\n    }\n  ]\n}\n~~~\n\nTo add a new Swift Xcode project, use the following template:\n\n~~~json\n{\n  \"repository\": \"Git\",\n  \"url\": \"https://github.com/example/project.git\",\n  \"path\": \"project\",\n  \"branch\": \"master\",\n  \"maintainer\": \"email@example.com\",\n  \"compatibility\": [\n    {\n      \"version\": \"4.2\",\n      \"commit\": \"195cd8cde2bb717242b3081f9c367ccd0a2f0121\"\n    }\n  ],\n  \"platforms\": [\n    \"Darwin\"\n  ],\n  \"actions\": [\n    {\n      \"action\": \"BuildXcodeProjectTarget\",\n      \"project\": \"project.xcodeproj\",\n      \"target\": \"project\",\n      \"destination\": \"generic/platform=iOS\",\n      \"configuration\": \"Release\"\n    }\n  ]\n}\n~~~\n\nAfter adding a new project to the index, ensure it builds successfully at the\npinned commits against the specified versions of Swift. In the examples,\nthe commits are specified as being compatible with Swift 4.2, which is included\nin Xcode 10.\n\n~~~bash\n# Select Xcode 10 GM\nsudo xcode-select -s /Applications/Xcode.app\n# Build project at pinned commit against selected Xcode\n./project_precommit_check project-path-field --earliest-compatible-swift-version 4.2\n~~~\n\nOn Linux, you can build against the Swift 4.2 release toolchain:\n\n~~~bash\ncurl -O https://swift.org/builds/swift-4.2-release/ubuntu1604/swift-4.2-RELEASE/swift-4.2-RELEASE-ubuntu16.04.tar.gz\ntar xzvf swift-4.2-RELEASE-ubuntu16.04.tar.gz\n./project_precommit_check project-path-field --earliest-compatible-swift-version 4.2 --swiftc swift-4.2-RELEASE-ubuntu15.10/usr/bin/swiftc\n~~~\n\n## Maintaining Projects\n\nIn the event that Swift introduces a change that breaks source compatibility\nwith a project (e.g., a compiler bug fix that fixes wrong behavior in the\ncompiler), project maintainers are expected to update their projects and submit\na new pull request with the updated commit hash within two weeks of being\nnotified. Otherwise, unmaintained projects may be removed from the project\nindex.\n\n## Contributing \nWelcome to the Swift community!\n\nContributions to /swift-source-compat-suite are welcomed and encouraged! Please see the [Contributing to Swift guide](swift.org/contributing) and check out the [structure of the community](https://www.swift.org/community/#community-structure).\n\nTo be a truly great community, Swift needs to welcome developers from all walks of life, with different backgrounds, and with a wide range of experience. A diverse and friendly community will have more great ideas, more unique perspectives, and produce more great code. We will work diligently to make the Swift community welcoming to everyone.\n\nTo give clarity of what is expected of our members, Swift has adopted the code of conduct defined by the Contributor Covenant. This document is used across many open source communities, and we think it articulates our values well. For more, see the [Code of Conduct](https://www.swift.org/code-of-conduct/).\n\n### Pull Request Testing\n\nPull request testing against the Swift source compatibility suite can be\nexecuted by commenting with `@swift-ci Please test source compatibility` in a\nSwift pull request.\n\n## Building Projects\n\nTo build all projects against a specified Swift compiler locally, use the\n`runner.py` utility as shown below.\n\n~~~bash\n./runner.py --swift-branch main --projects projects.json --include-actions 'action.startswith(\"Build\")' --swiftc path/to/swiftc\n~~~\n\nUse the `--include-repos` flag to build a specific project.\n\n~~~bash\n./runner.py --swift-branch main --projects projects.json --include-actions 'action.startswith(\"Build\")' --include-repos 'path == \"Alamofire\"' --swiftc path/to/swiftc\n~~~\n\nBy default, build output is redirected to per-action `.log` files in the current\nworking directory. To change this behavior to output build results to standard\nout, use the `--verbose` flag.\n\n## Marking actions as expected failures\n\nWhen an action is expected to fail for an extended period of time, it's\nimportant to mark the action as an expected failure to make new failures more\nvisible.\n\nTo mark an action as an expected failure, add an `xfail` entry for the correct\nSwift version and branch to the failing actions, associating each with a link\nto a JIRA issue reporting the relevant failure. The following is an example of\nan action that's XFAIL'd when building against Swift main branch in 4.2\ncompatibility mode.\n\n~~~json\n{\n  \"repository\": \"Git\",\n  \"url\": \"https://github.com/example/project.git\",\n  \"path\": \"project\",\n  \"branch\": \"master\",\n  \"maintainer\": \"email@example.com\",\n  \"compatibility\": [\n    {\n      \"version\": \"4.2\",\n      \"commit\": \"195cd8cde2bb717242b3081f9c367ccd0a2f0121\"\n    }\n  ],\n  \"platforms\": [\n    \"Darwin\"\n  ],\n  \"actions\": [\n    {\n      \"action\": \"BuildXcodeProjectTarget\",\n      \"project\": \"project.xcodeproj\",\n      \"target\": \"project\",\n      \"destination\": \"generic/platform=iOS\",\n      \"configuration\": \"Release\",\n      \"xfail\": {\n        \"issue\": \"https://github.com/apple/swift/issues/9999\",\n        \"compatibility\": \"4.2\",\n        \"branch\": \"main\"\n      }\n    }\n  ]\n}\n~~~\n\nAdditional Swift branches and versions can be added to XFAIL different\nconfigurations. The currently supported fields for XFAIL entries are:\n\n- `\"compatibility\"`: the Swift version(s) it fails with, e.g. `\"4.0\"`\n- `\"branch\"`: the branch(es) of the swift compiler it fails with, e.g.\n  `\"swift-5.1-branch\"`\n- `\"platform\"`: the platform(s) it fails on, e.g. `\"Darwin\"` or `\"Linux\"`\n- `\"configuration\"`: the build configuration(s) if fails with, i.e. `\"release\"`\n  or `\"debug\"`)\n- `\"job\"`: Allows XFailing the project for only the source compatibility build \n  or the SourceKit Stress Tester. Use `\"source-compat\"` to only XFail the Source \n  Compatibility Suite CI job and `\"stress-test\"` to only stress test the \n  SourceKit Stress Tester CI job.\n\nValues can either be a single string literal or a list of alternative string\nliterals to match against. For example the below action is expected to fail on\nboth main and swift-5.1-branch in both 4.0 and 5.1 compatibility modes:\n\n~~~json\n...\n{\n  \"action\": \"BuildXcodeProjectTarget\",\n  \"project\": \"project.xcodeproj\",\n  \"target\": \"project\",\n  \"destination\": \"generic/platform=iOS\",\n  \"configuration\": \"Release\",\n  \"xfail\": {\n    \"issue\": \"https://github.com/apple/swift/issues/9999\",\n    \"compatibility\": [\"4.0\", \"5.1\"],\n    \"branch\": [\"main\", \"swift-5.1-branch\"]\n  }\n}\n...\n~~~\n\nIf an action is failing for different reasons in different configurations, the\nvalue of the action's `\"xfail\"` entry can also become a list rather than\na single entry. In this case the `\"issue\"` of the first item that matches will\nbe reported. In the below example any failure on Linux would be reported as\n*SR-7777*, while a failure on other platforms would be reported as *SR-8888*\nusing a toolchain built from the *master* branch and *SR-9999* using a\ntoolchain built from *swift-5.1-branch*. If the entries were in the reverse\norder, *SR-7777* would only be reported for Linux failures with toolchains built\nfrom a branch other than *main* or *swift-5.1-branch*.\n\n~~~json\n...\n{\n  \"action\": \"BuildXcodeProjectTarget\",\n  \"project\": \"project.xcodeproj\",\n  \"target\": \"project\",\n  \"destination\": \"generic/platform=iOS\",\n  \"configuration\": \"Release\",\n  \"xfail\": [\n    {\n      \"issue\": \"https://github.com/apple/swift/issues/7777\",\n      \"platform\": \"Linux\"\n    },\n    {\n      \"issue\": \"https://github.com/apple/swift/issues/8888\",\n      \"branch\": \"main\"\n    },\n    {\n      \"issue\": \"https://github.com/apple/swift/issues/9999\",\n      \"branch\": \"swift-5.1-branch\"\n    }\n  ]\n}\n...\n~~~\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fswiftlang%2Fswift-source-compat-suite","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fswiftlang%2Fswift-source-compat-suite","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fswiftlang%2Fswift-source-compat-suite/lists"}