Swift 源代码兼容性

源代码兼容性是未来 Swift 版本的一个重要目标。为了帮助实现这一目标，一个社区拥有的源代码兼容性测试套件用于对编译器更改进行回归测试，测试对象是一个（逐渐增加的）Swift 源代码库。添加到此测试套件的项目会定期针对最新开发的 Swift 版本进行构建，作为 Swift 的持续集成系统的一部分，使 Swift 编译器开发人员能够了解他们的更改对真实 Swift 项目的兼容性影响。

当前项目列表

添加项目

Swift 源代码兼容性测试套件是社区驱动的，这意味着鼓励开源 Swift 项目的所有者提交符合验收标准的项目，以便将其纳入测试套件。添加到套件中的项目充当通用的源代码兼容性测试，并在未来的 Swift 版本中获得更强的保护，以防止意外的源代码破坏。

验收标准

要被 Swift 源代码兼容性测试套件接受，一个项目必须

目标平台为 Linux、macOS 或 iOS/tvOS/watchOS 设备
是一个 Xcode 或 Swift Package Manager 项目（目前不支持 Carthage 和 CocoaPods，但正在探索未来对其支持）
支持在 Linux 或 macOS 上构建
包含在公开可访问的 Git 仓库中
维护一个项目分支，该分支针对当前的 Swift GM 版本兼容模式构建，并通过任何单元测试
拥有维护者，他们承诺及时解决问题
与最新 GM/Beta 版本的 Xcode 和 swiftpm 兼容
添加尚未包含在套件中的价值
使用以下宽松许可证之一获得许可
- BSD
- MIT
- Apache License, version 2.0
- Eclipse Public License
- Mozilla Public License (MPL) 1.1
- MPL 2.0
- CDDL

注意：持续集成中的 Linux 兼容性测试尚不可用，但现在正在接受 Linux 项目。

添加项目

要添加符合验收标准的项目到套件，请执行以下步骤

确保项目在选定的提交版本上针对当前的 Swift GM 版本成功构建。
针对源代码兼容性套件仓库创建一个拉取请求，修改 projects.json 以包含对要添加到测试套件的项目的引用。

项目索引是一个 JSON 文件，其中包含一个仓库列表，这些仓库包含 Xcode 和/或 Swift Package Manager 目标操作。

要添加新的 Swift Package Manager 项目，请使用以下模板

{
  "repository": "Git",
  "url": "https://github.com/example/project.git",
  "path": "project",
  "branch": "main",
  "maintainer": "email@example.com",
  "compatibility": {
    "3.0": {
      "commit": "195cd8cde2bb717242b3081f9c367ccd0a2f0121"
    }
  },
  "platforms": [
    "Darwin"
  ],
  "actions": [
    {
      "action": "BuildSwiftPackage",
      "configuration": "release"
    },
    {
      "action": "TestSwiftPackage"
    }
  ]
}

commit 字段指定要将仓库固定到的提交哈希值。它包含在 compatibility 字段中，该字段指定提交版本已知与之兼容的 Swift 版本。可以指定与不同 Swift 版本兼容的多个提交版本。

platforms 字段指定可用于构建项目的平台。目前可以指定 Linux 和 Darwin。

如果不支持测试，请删除测试操作条目。

要添加新的 Swift Xcode 工作区，请使用以下模板

{
  "repository": "Git",
  "url": "https://github.com/example/project.git",
  "path": "project",
  "branch": "main",
  "maintainer": "email@example.com",
  "compatibility": {
    "3.0": {
      "commit": "195cd8cde2bb717242b3081f9c367ccd0a2f0121"
    }
  },
  "platforms": [
    "Darwin"
  ],
  "actions": [
    {
      "action": "BuildXcodeWorkspaceScheme",
      "workspace": "project.xcworkspace",
      "scheme": "project OSX",
      "destination": "platform=macOS",
      "configuration": "Release"
    },
    {
      "action": "BuildXcodeWorkspaceScheme",
      "workspace": "project.xcworkspace",
      "scheme": "project iOS",
      "destination": "generic/platform=iOS",
      "configuration": "Release"
    },
    {
      "action": "BuildXcodeWorkspaceScheme",
      "workspace": "project.xcworkspace",
      "scheme": "project tvOS",
      "destination": "generic/platform=tvOS",
      "configuration": "Release"
    },
    {
      "action": "BuildXcodeWorkspaceScheme",
      "workspace": "project.xcworkspace",
      "scheme": "project watchOS",
      "destination": "generic/platform=watchOS",
      "configuration": "Release"
    },
    {
      "action": "TestXcodeWorkspaceScheme",
      "workspace": "project.xcworkspace",
      "scheme": "project OSX",
      "destination": "platform=macOS"
    },
    {
      "action": "TestXcodeWorkspaceScheme",
      "workspace": "project.xcworkspace",
      "scheme": "project iOS",
      "destination": "platform=iOS Simulator,name=iPhone 7"
    },
    {
      "action": "TestXcodeWorkspaceScheme",
      "workspace": "project.xcworkspace",
      "scheme": "project tvOS",
      "destination": "platform=tvOS Simulator,name=Apple TV 1080p"
    }
  ]
}

要添加新的 Swift Xcode 项目，请使用以下模板

{
  "repository": "Git",
  "url": "https://github.com/example/project.git",
  "path": "project",
  "branch": "main",
  "maintainer": "email@example.com",
  "compatibility": {
    "3.0": {
      "commit": "195cd8cde2bb717242b3081f9c367ccd0a2f0121"
    }
  },
  "platforms": [
    "Darwin"
  ],
  "actions": [
    {
      "action": "BuildXcodeProjectTarget",
      "project": "project.xcodeproj",
      "target": "project",
      "destination": "generic/platform=iOS",
      "configuration": "Release"
    }
  ]
}

在将新项目添加到索引后，确保它在指定的 Swift 版本上针对固定的提交版本成功构建。在示例中，提交版本被指定为与 Swift 3.0 兼容，Swift 3.0 包含在 Xcode 8.0 中。

# Select Xcode 8.0 GM
sudo xcode-select -s /Applications/Xcode.app
# Build project at pinned commit against selected Xcode
./check project-path-field

在 Linux 上，您可以针对 Swift 3.0 发布工具链进行构建

curl -O https://download.swift.org/swift-3.0-release/ubuntu1510/swift-3.0-RELEASE/swift-3.0-RELEASE-ubuntu15.10.tar.gz
tar xzvf swift-3.0-RELEASE-ubuntu15.10.tar.gz
./check project-path-field --swiftc swift-3.0-RELEASE-ubuntu15.10/usr/bin/swiftc

维护项目

如果 Swift 引入了与项目源代码不兼容的更改（例如，修复了编译器中错误行为的编译器错误修复），则项目维护者应在收到通知后两周内更新他们的项目并提交包含更新的提交哈希值的新拉取请求。否则，未维护的项目可能会从项目索引中删除。

拉取请求测试

可以通过在 Swift 拉取请求中评论 @swift-ci Please test source compatibility 来执行针对 Swift 源代码兼容性套件的拉取请求测试。

构建项目

要在本地针对指定的 Swift 编译器构建所有项目，请使用 runner.py 实用程序，如下所示。

./runner.py --swift-branch main --projects projects.json --swift-version 3 --include-actions 'action.startswith("Build")' --swiftc path/to/swiftc

使用 --include-repos 标志来构建特定的项目。

./runner.py --swift-branch main --projects projects.json --swift-version 3 --include-actions 'action.startswith("Build")' --include-repos 'path == "Alamofire"' --swiftc path/to/swiftc

默认情况下，构建输出会重定向到当前工作目录中每个操作的 .log 文件。要将此行为更改为将构建结果输出到标准输出，请使用 --verbose 标志。