PackageTemplate

GitHub 上 Swift 包的模板

它稍微带有一些个人偏好，但主要是一些我发现有用的东西。欢迎根据需要进行自定义。如果您有任何改进的想法，请提交 issue 或 PR！

黄金法则：你的包名称不应该与包中的公共类型相同。这可能会导致编译器无法区分模块名称和类型名称的荒谬情况，过去这给我带来了很多麻烦。如果有人能给我发一篇关于此的博客文章或其他资料，我会在此处链接。

我喜欢使用 CapitalCase (首字母大写)。我不认为名称中应该包含 "Swift" 这个词。

它们目前都不适用于 Swift

GitHub 在这里提供了很大的控制权。我开始做最基本的：保护 main 分支免受意外的强制推送和删除。您可以轻松地通过 Settings（设置） > Code and automation（代码和自动化） > Branches（分支）来实现。为 main 添加一个规则，所有复选框都取消选中，即可完成。

这是非可选的。许多用户出于非常合理的原因，甚至不会查看没有许可证的包。GitHub 使这变得很容易。我一直是 BSD 3-条款许可证的长期用户。它非常宽松，类似于 MIT，但同时也明确限制了相关人员的隐含认可。

总的来说，我不喜欢病毒式许可证，尤其是当这种病毒性适用于链接时。但是，我理解为什么它被设计成这样。防止开源滥用和利用非常重要，您选择的许可证确实很重要。

“让我们彼此善待” 很好！但是，拥有一套关于这实际上意味着什么的具体规则，以及如果这些规则被打破会发生什么，这一点很重要。贡献者公约 (Contributor Covenant) 已经变得很流行，我认为这是一个很好的选择。

我喜欢在我的仓库上添加一些徽章，以提供一些一目了然的信息。我认为很容易做得过头，但你也应该乐于将其个性化！

许多人发现明确的包安装说明很有帮助，即使只是为了方便地复制粘贴到另一个 Package.swift 文件中。我喜欢包含它们，但您必须注意两件事。

• 您应该定期增加您的版本号
• 包含不同名称库的包需要更明确的依赖规范

dependencies: [
    .package(url: "https://github.com/ChimeHQ/PackageTemplate", from: "1.0.0")
],
targets: [
    .target(
        name: "UseCoreFunctionality",
        dependencies: ["PackageTemplate"]
    ),
    .target(
        name: "UsesDifferentProduct",
        dependencies: [.product(name: "AnotherProduct", package: "PackageTemplate")]
    ),
]

如果您正在使用 GitHub 赞助，您就知道它是如何工作的。但以防万一，请不要将我的 .github/FUNDING.yml 复制到您自己的项目中。

长期以来，我认为将平台留空是最兼容的做法。但是，这会将有效的平台/版本留给编译器决定。并且，这可能会产生随着时间推移而变化的令人惊讶的结果。明确指定是最好的。

这允许两件事：更好的并发检查和 visionOS 支持。在没有编译器检查的情况下使用并发是一个坏主意。并且您可能在不知不觉中使用它。我已将此功能全面开启，适用于所有目标。它有点难看，但我更喜欢拥有最大的检查和功能，而无需在添加目标时手动调整。

let swiftSettings: [SwiftSetting] = [
    .enableExperimentalFeature("StrictConcurrency"),
    .enableUpcomingFeature("DisableOutwardActorInference"),
    .enableUpcomingFeature("GlobalActorIsolatedTypesUsability"),
    .enableUpcomingFeature("InferSendableFromCaptures"),
]

for target in package.targets {
    var settings = target.swiftSettings ?? []
    settings.append(contentsOf: swiftSettings)
    target.swiftSettings = settings
}

我从 Keith Harrison 那里获得了这个想法。

另外，值得注意的是，我在此处添加了 Swift 5.10 中可用的功能。但是，您可能还想采用一些 Swift 6 的功能。您可以通过在源代码中使用条件编译来实现这一点，而不会牺牲与 5.10 的兼容性。

GitHub actions 大部分都很棒。但是有两件事使它们变得非常糟糕。GitHub 在引入新版本的 macOS 时非常缓慢。这意味着 "macOS-latest" 永远不会是最新发布的 macOS 版本。仅凭这一点对于支持 macOS 的软件包来说可能就是一个问题。但是，它也可能影响默认的 Xcode 版本。

第二个问题是模拟器名称会更改，并且 xcodebuild 使人们很难不在意。

我已经放弃依赖于此处的默认设置，并且我总是明确地进行设置。不幸的是，这意味着需要手动维护，尤其是在 WWDC 期间。

• 主机操作系统
• Xcode 版本
• 模拟器名称

如果您有技巧/黑客/自定义操作来使其更好，请告诉我。

注意！如果您的包的 products 数组中包含多个条目，则需要将 -Package 附加到方案名称，才能使 xcodebuild 测试正常工作。

SPI 是一个简单的选择。

如果我对库有一个想法，我总是首先在 SPI 上进行搜索。

有点像迷你 CI。 SPI 将为许多 swift/平台组合构建您的包。我认为从一开始就明确您的包支持哪些平台非常有用。

也许是最被低估的功能。如果您在您的包中包含 DocC，SPI 将为您托管它。您需要一个 .spi.yml 文件才能使其工作。

长期以来，我认为 tabs (制表符) 与 spaces (空格) 是一件不值得争论的愚蠢事情。然后有一天我了解到 tabs 可以为弱视人群提供辅助功能改进。 并且同样的优势也有助于以人们喜欢的方式设置代码样式。所以我切换到了 tabs，我鼓励你也这样做。

Xcode 支持 editorconfig，我认为包含它是一个好主意。

我很乐意收到你的来信！通过 mastodon、一个 issue 或一个 pull request 与我联系。

通过参与本项目，您同意遵守贡献者行为准则。