跳到主要内容

为 SideStore 做贡献

感谢你有兴趣为 SideStore 做贡献。SideStore 是一个由社区驱动的项目，正是像你这样的人让它成为可能。

通过为这个项目（SideStore）做出贡献，你同意在 CERTIFICATE-OF-ORIGIN.md 中找到的开发者来源证书（Developer's Certificate of Origin）。在添加开发者来源证书之后对此项目的任何贡献均受其政策的约束。

有很多方式可以为 SideStore 做贡献，所以如果你不是开发者，还有很多其他方式可以帮助：

不过，本指南将侧重于开发方面。目前我们只包含设置信息，但如果你在设置后需要帮助，可以加入我们的 Discord。

要求​

本指南假设你：

  • 使用的是 Mac
  • 已安装 Xcode
  • 具备基本命令行知识（知道如何运行命令，cd 到目录）
  • 具备基本 Git 知识（GitHub Desktop 是初学者的绝佳工具，并且大大简化了 Git 的使用）
  • 具备基本 Swift/iOS 开发知识

设置​

  1. 在 GitHub 上 fork SideStore 仓库。

  2. 克隆你的 fork：

    git clone https://github.com/<your-github-username>/SideStore.git --recurse
    cd SideStore

    如果你使用的是 GitHub Desktop，请参考这篇指南。

  3. 将 CodeSigning.xcconfig.sample 复制为 CodeSigning.xcconfig 并填入相应的值。

  4. （仅限开发） 将 Info.plist 中 ALTDeviceID 的值改为你设备的 UDID。通常，iloader 会在安装期间将设备的 UDID 嵌入到 SideStore 的 Info.plist 中。在通过 Xcode 运行时，你需要自己设置该值，否则 SideStore 将无法为相应的设备重新签名（甚至无法安装）应用。

  5. 最后，在 Xcode 中打开 AltStore.xcworkspace。

接下来，进行修改并测试。然后使用 git 提交并推送你的更改，并发起一个 pull request。

预构建二进制信息​

minimuxer 和 em_proxy 使用由 GitHub Actions 构建的预构建静态库二进制文件，以加快构建速度并消除在处理 SideStore 时需要安装 Rust 的需求。Xcode 会在每次构建前运行 SideStore/fetch-prebuilt.sh，并且每 6 小时检查一次下载的二进制文件是否为最新。如果你想强制检查新的二进制文件，请运行 bash ./SideStore/fetch-prebuilt.sh force。

使用 Xcode 构建​

如需要请安装 cocoapods：brew install cocoapods
现在在仓库工作区根目录下使用命令行执行 Pod-Install：使用 pod install 命令安装 cocoapod 依赖。
之后你就可以在 Xcode 中进行常规构建了。

构建用于分发的 IPA​

如需要请安装 cocoapods：brew install cocoapods
现在在仓库工作区根目录下使用命令行执行 Pod-Install：使用 pod install 命令安装 cocoapod 依赖。

然后你可以在根目录使用 Makefile 命令：make build fakesign ipa。
默认的构建配置为：Release
对于调试构建：在根目录执行 export BUILD_CONFIG=Debug;make build fakesign ipa。
对于 alpha/beta 构建：在调用构建命令之前设置 export IS_ALPHA=1; 或 export IS_BETA=1;。
这将生成 SideStore.ipa。

示例：

    # cocoapods
    brew install cocoapods
    # 执行安装 pods
    pod install

    # alpha 发布构建
    export IS_ALPHA=1;make build fakesign ipa
    # alpha 调试构建
    export IS_ALPHA=1;export BUILD_CONFIG=Debug;make build fakesign ipa

    # beta 发布构建
    export IS_BETA=1;make build fakesign ipa
    # beta 调试构建
    export IS_BETA=1;export BUILD_CONFIG=Debug;make build fakesign ipa

    # 正式发布构建
    make build fakesign ipa
    # 正式调试构建
    export BUILD_CONFIG=Debug;make build fakesign ipa

默认情况下 SideStore 会以其默认的 bundleIdentifier com.SideStore.SideStore 构建，但如果你需要为命令行构建设置自定义 bundleID，可以通过导出 BUNDLE_ID_SUFFIX 环境变量来实现：

    # 正式发布构建
    export BUNDLE_ID_SUFFIX=XYZ0123456;make build fakesign ipa
    # 正式调试构建
    export BUNDLE_ID_SUFFIX=XYZ0123456;export BUILD_CONFIG=Debug;make build fakesign ipa

注意：在从 XCode 构建时，BUNDLE_ID_SUFFIX 默认设置为 DEVELOPMENT_TEAM 的值。

可以通过在由 CodeSigning.xcconfig.sample 创建的 CodeSigning.xcconfig 中设置/移除 BUNDLE_ID_SUFFIX 来自定义此值。

注意

生成的二进制文件将包含到 Xcode 的 DerivedData 的路径，如果你在自己机器上构建了 minimuxer，还会包含到 $HOME/.cargo 的路径。这会包含你的用户名。如果你想保持用户名的私密性，你可能希望让 GitHub Actions 来构建 IPA。

与 SideStore 一同开发 minimuxer​

请参阅 minimuxer 的 README 获取开发说明。

Pull Request 流程​

提交之前​

  1. 遵循代码标准：确保你的代码符合我们的格式化指南。

  2. 测试你的更改：

    • 尽可能在不同的 iOS 版本上测试
    • 确保现有功能没有被破坏
    • 在适用时为新功能添加测试

  3. 更新文档：如果你的更改影响了面向用户的功能，请更新相关文档。

提交你的 PR​

  1. 创建一个功能分支：

    git checkout -b feature/your-feature-name

  2. 进行你的修改：遵循编码指南和最佳实践。

  3. 使用签名提交你的更改：

    git add .
    git commit -s -m "Add descriptive commit message"

    重要：所有提交都应使用开发者来源证书（DCO）进行签名。-s 标志会自动在提交信息中添加必要的 Signed-off-by 行。

  4. 推送到你的 fork：

    git push origin feature/your-feature-name

  5. 创建 Pull Request：前往主 SideStore 仓库，从你的分支创建一个 pull request。

警告

我们不接受明显由 AI 生成或“vibe-coded”的 pull request（例如，过多的明显注释、看起来千篇一律且缺乏对项目的理解、或并非为 SideStore 用心制作的代码）。请确保你的贡献是原创的，并显示出对代码库及其目标的清晰理解。

PR 指南​

  • 清晰的标题：使用描述性标题来概括所做的更改
  • 详细的描述：说明你做了哪些更改以及为什么
  • 关联相关问题：引用任何相关的 GitHub issues
  • 截图：为 UI 更改包含截图
  • 测试说明：描述你是如何测试你的更改的

开发者来源证书（DCO）​

SideStore 要求所有贡献者使用开发者来源证书（DCO）签署他们的提交。这作为我们的贡献者行为准则。它也证明了你编写了所贡献的代码、或拥有提交它的权利。

什么是 DCO？​

通过签署你的提交，你证明：

  • (a) 该贡献全部或部分由你创建，并且你有权根据文件中指定的开源许可证提交它；或
  • (b) 该贡献基于先前的成果，据你所知，该成果受到适当的开源许可证的保护，并且你有权在该许可证下提交带有修改的该成果；或
  • (c) 该贡献由其他某个已认证 (a)、(b) 或 (c) 的人直接提供给你，并且你没有修改它。
  • (d) 你理解并同意此项目和此贡献是公开的，并且该贡献的记录会被无限期保留。

如何签名​

要签署你的提交，只需在提交时添加 -s 标志：

git commit -s -m "Your commit message"

这将会自动在你的提交信息中添加一行 Signed-off-by：

Your commit message

Signed-off-by: SternXD <[email protected]>

重要说明​

  • 所有提交都应被签名 - 我们通常更希望你签名提交。
  • 使用正确的邮箱 - 邮箱应与你的 GitHub 账户匹配。
  • 追溯签名 - 如果你忘记签名，你可以使用 git commit --amend -s 修改你上一条提交。

如需了解更多详情，请参阅完整的开发者来源证书文档。

代码审查流程​

  1. 初始审查：维护者会在几天内审查你的 PR
  2. 反馈：处理任何要求的更改或问题
  3. 最终批准：一旦获得批准，维护者会合并你的 PR

优秀贡献的指南​

代码质量​

  • 编写干净、可读的代码
  • 遵循 Swift 和 Objective-C 的最佳实践
  • 使用有意义的变量和函数名
  • 为复杂的代码添加注释

测试​

  • 尽可能在实体设备上测试
  • 测试边界情况和错误条件
  • 验证向后兼容性

文档​

  • 更新代码注释
  • 更新面向用户的文档
  • 为公共 API 包含内联文档

获取帮助​

如果你需要帮助或有疑问：

  • GitHub Discussions：在 GitHub Discussions 上提问一般问题
  • GitHub Issues：为 bug 或功能请求创建 issue
  • Discord：加入 SideStore Discord 社区

致谢​

做出重大贡献的贡献者将在项目的致谢和变更日志中得到认可。

感谢你为 SideStore 做贡献。