Container-Compose 贡献代码指南：如何从 Fork 到提交 PR 快速上手-育师

【免费下载链接】Container-Compose

A docker-compose like tool for Apple Container

项目地址：https://gitcode.com/gh_mirrors/con/Container-Compose

Container-Compose 是一个为 Apple Container 提供类 Docker Compose 支持的命令行工具，用 Swift 编写。本文带你完整走完 Container-Compose 贡献代码的全流程：从 Fork 仓库、本地构建、理解代码结构、补充测试，到最终提交 PR，并附上项目关键文件的相对路径，帮助新手快速上手开源协作。

1. 项目速览：Container-Compose 是什么？

在贡献代码之前，先搞清楚这个项目解决什么问题：

核心定位：解析docker-compose.yml文件，将多容器应用编排到 Apple Container 运行时上。它不是 Docker 的包装器，而是将 Compose 工作流桥接到苹果容器生态的独立工具。
技术栈：Swift 6.1 + swift-argument-parser 构建 CLI，Yams 解析 YAML，依赖 Apple 官方的container包（见 Package.swift）。
运行环境：macOS 15+，建议 macOS 26 (Tahoe) 以获得完整体验（macOS 15 需手动处理 DNS）。

💡 贡献前的第一功课：花 10 分钟阅读 README.md，并在自己的 Mac 上用 Homebrew 或源码方式跑一次工具，建立直观感受。

2. 开发环境搭建：构建与测试命令

2.1 前置要求

一台运行 macOS 的 Mac（Sonoma 或更新版本）
Git 与 Xcode Command Line Tools
Apple Container 运行时（动态测试需要）

2.2 克隆仓库

git clone https://gitcode.com/gh_mirrors/con/Container-Compose cd Container-Compose

2.3 常用构建命令

项目的构建入口是 Makefile，封装了 Swift Package Manager 命令：

make build # 等价于 swift build -c release --disable-sandbox make install # 构建后安装到 /usr/local/bin make clean # 清理 .build 目录

构建产物位于.build/release/container-compose。

2.4 运行测试

项目使用 Swift 官方Testing 框架（import Testing、#expect断言），测试分为两套（见 Package.swift 的 target 定义）：

测试套件	路径	是否需要容器运行时
StaticTests（解析/静态逻辑）	Tests/Container-Compose-StaticTests/	否
DynamicTests（真实起容器）	Tests/Container-Compose-DynamicTests/	是

# 推荐：仅跑静态测试，速度快、无需容器环境 swift test --filter Container-Compose-StaticTests

动态测试（如 ComposeUpTests.swift）会真实拉取镜像、创建容器，需要 Apple Container 已启动；如果本地环境受限，跑通静态测试即可作为 PR 的基本保障。

3. 读懂项目结构：改代码前先看这里

整个代码库非常小巧，核心逻辑集中在一个模块里：

Sources/ ├── Container-Compose/ # 核心模块 ContainerComposeCore │ ├── Application.swift # 命令入口：注册 up/down/build 子命令 │ ├── ComposeProject.swift # 项目加载与编排逻辑 │ ├── Commands/ # 各子命令实现 │ │ ├── ComposeUp.swift # compose up（最复杂，1500+ 行） │ │ ├── ComposeDown.swift # compose down │ │ └── ComposeBuild.swift # compose build │ └── Codable Structs/ # Compose 文件的 YAML 映射结构 │ ├── DockerCompose.swift # 顶层结构：services/volumes/networks… │ ├── Service.swift # 单个服务定义 │ └── ... └── ContainerComposeApp/ # 可执行入口（极小）

三类典型改动与对应文件：

新增子命令（如compose ps）：参考 ComposeDown.swift 实现AsyncParsableCommand，然后在 Application.swift 的subcommands数组中注册；
支持新的 Compose 字段：在 Codable Structs/ 中对应结构体添加字段（可参考 DockerCompose.swift 的自定义init(from:)写法），并为解析逻辑补充静态测试；
修复编排逻辑：先阅读 ComposeUp.swift 中的等待、健康检查等 actor 实现，再动手修改。

📌 测试辅助工具在 Tests/TestHelpers/DockerComposeYamlFiles.swift，内置了 WordPress、三层 Web 应用等示例 YAML，写测试时可直接复用。仓库还提供了真实场景样例 Sample Compose Files/Healthchecked Redis/docker-compose.yaml（带 healthcheck 的 Redis 服务）。

4. 如何写测试：以现有风格为准

项目测试风格清晰，直接模仿即可。静态测试示例（摘自 ComposeBuildParsingTests.swift）：

@Test("Services with build config are selected for building") func servicesWithBuildConfigAreSelected() throws { let yaml = """ services: app: build: context: . """ let compose = try YAMLDecoder().decode(DockerCompose.self, from: yaml) #expect(compose.services.count == 1) }

写测试的三条建议：

用@Suite+@Test组织，测试方法名使用描述性英文（如testCpuAndMemoryLimits）；
用#expect/#require断言，避免手写XCTAssert；
涉及容器行为的断言（端口、镜像引用、环境变量、挂载点）参考 ComposeUpTests.swift 中testComposeUpWithExplicitIPPortMapping的写法。

5. 从 Fork 到提交 PR：6 步完整流程

以下步骤与 CONTRIBUTING.md 保持完全一致：

第 1 步：Fork 并克隆仓库

git clone https://gitcode.com/gh_mirrors/con/Container-Compose cd Container-Compose

第 2 步：创建功能分支

项目约定分支前缀feat/（修复问题可用fix/）：

git checkout -b feat/YourFeature

第 3 步：修改代码并提交

git commit -am 'Add new feature'

第 4 步：为改动补充测试

这是项目的明确要求——改动必须附带测试（参见 CONTRIBUTING.md 第 4 条）。至少保证：

swift build -c release --disable-sandbox # 编译通过 swift test --filter Container-Compose-StaticTests # 静态测试通过

第 5 步：推送分支

git push origin feat/YourFeature

第 6 步：提交 Pull Request

在仓库页面发起 PR 后，建议描述中包含：

改动摘要（解决了什么问题 / 新增了什么能力，可引用 Issue 编号）
测试情况说明（跑了哪些测试、动态测试是否受限）
若新增命令或字段，附一个最小 Compose 文件示例

6. 新手常见贡献方向（由易到难）

🐛Bug 修复：动态测试里不少// TODO: Reenable的注释块（如 ComposeUpTests.swift 中被注释的多网络三层应用测试）就是等待修复的功能；
🧩字段支持：Compose 规范仍在演进，为 Service.swift 等结构补齐字段是低风险的入门任务；
🧪测试补充：为现有功能补静态解析测试，无需容器环境；
📝文档完善：修正 README.md 或 CONTRIBUTING.md 中的笔误同样有价值。