Mirror the shared Swift rules canon (rules-swift, commit 4ebb892) into docs/rules-swift/ as a read-only reference alongside the repo's tailored docs/rules/. PROVENANCE.md records the source, commit, and what was included or excluded; the upstream repo's own VCS, CI, and lint tooling is omitted as machinery rather than rule content. Exclude the vendored tree from the style gate (scripts/check-style.sh) and the pre-commit hook: the canon's enforcement docs quote the forbidden attribution phrases to define them, the same reason the repo's own enforcement files are already excluded.
136 lines
5.3 KiB
Markdown
136 lines
5.3 KiB
Markdown
# When to Create a New Package
|
|
|
|
Always-loaded core. Use the decision tree first. The DO/DON'T list and the checklist below cover the corner cases.
|
|
|
|
## PACKAGE CREATION DECISION TREE
|
|
|
|
```
|
|
Need to add new code?
|
|
├─ Is it a reusable domain model?
|
|
│ └─ YES → Add to SharedModels
|
|
│
|
|
├─ Is it UI-related?
|
|
│ ├─ Colors/semantic colors? → Add to AppColors
|
|
│ ├─ Fonts/typography? → Add to AppFont
|
|
│ ├─ Combined theme? → Add to AppTheme (uses AppColors + AppFont)
|
|
│ ├─ Component system infrastructure? → Add to Components (core system)
|
|
│ ├─ Hot reload support? → Add to SharedComponents
|
|
│ ├─ Reusable app component? → Add to AppComponents
|
|
│ └─ View helper/modifier? → Add to SharedViews
|
|
│
|
|
├─ Is it a complete user-facing feature?
|
|
│ └─ YES → Create new *Feature package
|
|
│ Example: ProfileFeature, SettingsFeature, PaymentFeature
|
|
│
|
|
├─ Is it API/networking related?
|
|
│ ├─ Client-side? → Add to ApiClient (or create new client package)
|
|
│ ├─ Server-side? → Add to ApiServer
|
|
│ ├─ Shared DTOs? → Add to ApiShared (OpenAPI generated)
|
|
│ └─ Middleware? → Create new *Middleware package
|
|
│
|
|
├─ Is it shared infrastructure?
|
|
│ └─ YES → Create new Shared* package
|
|
│ Example: SharedUtilities, SharedNetworking
|
|
│
|
|
└─ Still unsure?
|
|
└─ Ask: "Could this be reused in isolation?"
|
|
├─ YES → Create new package
|
|
└─ NO → Add to most specific existing package
|
|
```
|
|
|
|
## WHEN TO CREATE A NEW PACKAGE
|
|
|
|
### ✅ DO Create New Package When:
|
|
|
|
1. **New Feature Module**
|
|
- Complete user-facing feature (login, profile, payments)
|
|
- Example: `ProfileFeature`, `PaymentFlowFeature`
|
|
|
|
2. **Reusable Infrastructure**
|
|
- Can be tested in isolation
|
|
- Might be used by multiple features
|
|
- Example: `CachingMiddleware`, `LoggingUtility`
|
|
|
|
3. **Third-Party Integration**
|
|
- Wraps external library
|
|
- Isolates external dependencies
|
|
- Example: `ApplePayIntegration`, `BiometricAuth`
|
|
|
|
4. **Platform Separation**
|
|
- Platform-specific code (iOS vs macOS)
|
|
- Example: `IOSBiometrics`, `MacOSNotifications`
|
|
|
|
5. **Build Optimization**
|
|
- Large, stable code that rarely changes
|
|
- Expensive compilation (generated code)
|
|
- Example: `ApiShared` (OpenAPI generated)
|
|
|
|
### ❌ DON'T Create New Package When:
|
|
|
|
1. **Single Use Case**
|
|
- Only used by one feature
|
|
- Tightly coupled to specific screen
|
|
- → Add to that feature's package
|
|
|
|
2. **Trivial Helper**
|
|
- 1-2 small functions
|
|
- No external dependencies
|
|
- → Add to existing utility package
|
|
|
|
3. **Temporary Code**
|
|
- Proof of concept
|
|
- Spike/experiment
|
|
- → Keep in feature until proven stable
|
|
|
|
## DECISION CHECKLIST
|
|
|
|
### Before Creating a New Package
|
|
|
|
- [ ] Package has single, clear responsibility
|
|
- [ ] Package name follows conventions (*Feature, Shared*, Api*, *Components)
|
|
- [ ] Dependencies are minimal and explicit
|
|
- [ ] No circular dependencies introduced
|
|
- [ ] Can be built and tested in isolation
|
|
- [ ] Fits into architectural layer (Foundation/Infrastructure/Feature/App)
|
|
- [ ] Test target created alongside source target
|
|
- [ ] Product registered in Package.swift products array
|
|
- [ ] Dependencies only flow upward (no higher-layer dependencies)
|
|
|
|
### Before Adding to Existing Package
|
|
|
|
- [ ] New code shares responsibility with existing code
|
|
- [ ] No better-suited package exists
|
|
- [ ] Not creating a "God package" with mixed concerns
|
|
- [ ] Won't introduce unwanted dependencies to package consumers
|
|
|
|
### Before Modifying Package.swift
|
|
|
|
- [ ] Used closure-with-local-variables pattern for `deps`
|
|
- [ ] Used closure-with-local-variables pattern for `allProducts`
|
|
- [ ] Used closure-with-local-variables pattern for `targets`
|
|
- [ ] NEVER used inline array definitions
|
|
- [ ] Grouped dependencies by purpose (OpenAPI, Vapor, Apple-only, etc.)
|
|
- [ ] Grouped products by platform (base vs. appleOnly)
|
|
- [ ] Grouped targets by layer (Foundation, Infrastructure, Features)
|
|
- [ ] Used comment headers (e.g., `// ---------- Shared Models ----------`)
|
|
- [ ] In `Package.swift`: separated platform-specific code with `#if os(iOS) || os(macOS)`
|
|
- [ ] In `Package.swift` only: did NOT use `#if canImport(UIKit)` (manifest evaluates it lazily and breaks Linux CI; `#if os()` is manifest-parse-time and safe). In regular Swift source files, `#if canImport(UIKit)` / `#if canImport(AppKit)` is the correct idiom for platform-conditional code.
|
|
- [ ] Each target/product/dependency has descriptive variable name
|
|
- [ ] Used trailing commas in all arrays
|
|
- [ ] Applied `.when(platforms:)` for platform-specific dependencies within targets
|
|
|
|
### Before Adding Font/Resource Package
|
|
|
|
- [ ] Used `.process()` for resources, NEVER `.copy()`
|
|
- [ ] Created `FontRegistration.swift` with CoreText registration
|
|
- [ ] Used `Bundle.module` for resource access, NEVER `Bundle.main`
|
|
- [ ] Used `#if canImport(UIKit)` / `#if canImport(AppKit)` for platform imports
|
|
- [ ] Filtered font files by extension (.otf, .ttf)
|
|
- [ ] Used `CTFontManagerRegisterFontsForURL` with error handling
|
|
- [ ] Added console logging for registration success/failure
|
|
- [ ] Called `FontRegistration.registerFonts()` in app init BEFORE UI renders
|
|
- [ ] NEVER used Info.plist font registration (`UIAppFonts`, `ATSApplicationFontsPath`)
|
|
- [ ] Package has zero dependencies (fonts are Foundation layer)
|
|
- [ ] Resources organized in dedicated subdirectory (e.g., `Fonts/`)
|
|
|