shipit — Product Requirements Document

1. Problem Statement

Small teams deploy with ad-hoc shell scripts that differ per machine and break silently. shipit is a single, predictable command-line tool that runs a project's deploy steps the same way everywhere, with clear output and safe rollbacks.

2. Product Vision

A deploy CLI that "just works" from a tiny config file — readable output, sensible defaults, and zero servers to run. Built for Python projects first, language-agnostic later.

3. Goals & Success Metrics

• Time-to-first-deploy: a new user deploys a sample app in under 5 minutes.
• Reliability: failed deploys roll back automatically; non-zero exit code on any error.
• Adoption: 1,000 installs via pip/pipx in the first quarter.

4. Command Structure

• shipit init — scaffold a shipit.toml config.
• shipit deploy [--env staging|prod] [--dry-run] — run the deploy pipeline.
• shipit rollback [--to <release>] — revert to a previous release.
• shipit status — show the current release and history.

5. Functional Requirements

• Read steps from shipit.toml; support env-specific overrides.
• Stream step output live; stop on first failure.
• --dry-run prints the plan without executing.
• Secrets read from environment variables, never stored in config.

6. Non-Functional Requirements

• Cross-platform (macOS, Linux); clear, colorized output that degrades gracefully when piped.
• Helpful --help for every command; meaningful exit codes.
• No telemetry without explicit opt-in.

7. Configuration (shipit.toml)

8. Distribution

• Published to PyPI; installable via pip install shipit or pipx install shipit.
• Semantic versioning; changelog per release.

9. Milestones

• Phase 1 (2 wks): init + deploy with live output and --dry-run.
• Phase 2 (1 wk): rollback + status with release history.
• Phase 3 (1 wk): PyPI packaging, docs, and --help polish.

10. Risks & Open Questions

• Step failures mid-deploy must leave the system in a known state.
• Open: should config be TOML only, or also support YAML for teams that prefer it?