mirror of
https://github.com/phranck/TUIkit.git
synced 2026-05-21 09:50:35 +00:00
phranck
6c1bda94bf
- Move all plans from plans/ to .claude/plans/ (41 files) - Add open plans listing to whats-next.md for visibility - Update docs pipeline (update-plans-data.ts) for new paths - Rewrite .github/copilot-instructions.md with Swift 6.0 constraint - Add CONTRIBUTING.md, PR template, AGENTS.md, .cursor/rules, .windsurfrules - Update global references (~/.claude/CLAUDE.md, project-structure.md)
85 lines
2.7 KiB
Markdown
85 lines
2.7 KiB
Markdown
# Contributing to TUIkit
|
|
|
|
TUIkit is a SwiftUI-like framework for building Terminal User Interfaces in pure Swift, with no ncurses or C dependencies. It targets SwiftUI API parity wherever possible.
|
|
|
|
## Hard Requirements (non-negotiable)
|
|
|
|
| Requirement | Details |
|
|
|-------------|---------|
|
|
| **Swift 6.0** | `swift-tools-version: 6.0`. Never use features from a newer compiler. |
|
|
| **Cross-platform** | Must build and run on both macOS and Linux. CI tests both (`macos-15` + `swift:6.0` container). |
|
|
| **CI must pass** | All tests and linting must pass before merge. |
|
|
|
|
## Build, Test & Lint
|
|
|
|
```bash
|
|
# Build
|
|
swift build
|
|
|
|
# Run all tests (1037+ tests, Swift Testing framework)
|
|
swift test
|
|
|
|
# Run a single test suite
|
|
swift test --filter <TestSuiteName>
|
|
|
|
# Lint
|
|
swiftlint
|
|
|
|
# Format (configured but not enforced in CI)
|
|
swift-format format -i -r Sources Tests
|
|
```
|
|
|
|
## Pull Request Requirements
|
|
|
|
1. Branch from `main`
|
|
2. Fill in the PR template completely
|
|
3. CI must be green (macOS + Linux)
|
|
4. No new SwiftLint warnings
|
|
5. Follow the architecture and API rules below
|
|
|
|
## Architecture
|
|
|
|
### SwiftUI API Parity
|
|
|
|
Public APIs **must** match SwiftUI signatures exactly unless terminal constraints require deviation (document why in comments).
|
|
|
|
| Aspect | Requirement |
|
|
|--------|-------------|
|
|
| Parameter names | Exact (`isPresented`, not `isVisible`) |
|
|
| Parameter order | Exact (title, binding, actions, message) |
|
|
| Parameter types | Match closely (ViewBuilder closures, not pre-built values) |
|
|
| Trailing closures | `@ViewBuilder () -> T`, not `String` |
|
|
|
|
**Before implementing any SwiftUI-equivalent API:** Look up the exact SwiftUI signature first.
|
|
|
|
### View Architecture
|
|
|
|
- Every **public** control must be a `View` with a real `body: some View`
|
|
- The `body` must return actual Views (not `Never`, not `fatalError()`)
|
|
- `Renderable` is only for leaf nodes (`Text`, `Spacer`, `Divider`) and private `_*Core` views
|
|
- All modifiers must propagate through the entire View hierarchy
|
|
- Environment values must flow down automatically
|
|
|
|
### General Principles
|
|
|
|
- No singletons
|
|
- Search the codebase for similar patterns before implementing anything new
|
|
- Consolidate and reuse before adding new functions or types
|
|
|
|
## Code Style
|
|
|
|
- Line length: 140 characters (warning), 200 (error)
|
|
- 4-space indentation
|
|
- Trailing commas in multi-line collections
|
|
- See `.swiftlint.yml` and `.swift-format` for full configuration
|
|
|
|
## Testing
|
|
|
|
- Uses Swift Testing framework (`@Test`, `#expect`, `@Suite`)
|
|
- Tests run in parallel
|
|
- Test files mirror source structure in `Tests/TUIkitTests/`
|
|
|
|
## Detailed Architecture Rules
|
|
|
|
For comprehensive architecture documentation including the `_*Core` pattern, focus system, state management, and interactive view rules, see [`.claude/CLAUDE.md`](.claude/CLAUDE.md).
|