Metadata-Version: 2.4
Name: fship
Version: 0.1.1
Summary: Flutter Ship — orchestrate release workflows to Firebase App Distribution
Project-URL: Homepage, https://github.com/MrShakila/F-ship
Project-URL: Repository, https://github.com/MrShakila/F-ship
Project-URL: Issues, https://github.com/MrShakila/F-ship/issues
Author-email: Shakila <shadikari012@gmail.com>
License: MIT
Requires-Python: >=3.11
Requires-Dist: pyyaml>=6.0
Requires-Dist: rich>=13.7
Requires-Dist: ruamel-yaml>=0.18
Requires-Dist: typer[all]>=0.12
Description-Content-Type: text/markdown

# fship — Flutter Ship

Memorable, easy CLI for orchestrating Flutter release workflows to Firebase App Distribution.

```bash
fship release qa                    # Interactive version bump + full release
fship release qa --version 1.2.4+46  # Exact version
fship release qa --bump patch       # Auto-increment patch
```

## Quick Start

1. **Install**: `pip install fship`
2. **Initialize**: `cd /path/to/flutter/project && fship init`
3. **Configure**: Edit `fship.yaml` with your Firebase app IDs
4. **Validate**: `fship validate`
5. **Release**: `fship release qa` (or your flavor name)

## Why fship?

**Problem:** Manual Flutter releases to Firebase App Distribution are tedious and error-prone.
- Manual version bumping in pubspec.yaml
- Manual changelog creation
- Manual git tagging
- Manual APK building for each flavor
- Manual Firebase distribution
- Human error: wrong version, missing tags, incomplete changelogs

**Solution:** fship automates the entire workflow in one command.

## Features

✓ **Interactive or Automated Version Bumping**
- Interactive: choose version interactively
- Auto-increment: patch, minor, or major
- Exact version: specify exact version number

✓ **Changelog Generation**
- Auto-generate CHANGELOG.md from git history
- Uses git-chglog for professional formatting
- Customizable changelog templates

✓ **Git Integration**
- Auto-commit version changes
- Auto-create git tags
- Track release history in git

✓ **Multi-Flavor Support**
- Separate configurations per flavor (qa, uat, prod)
- Flavor-specific entrypoints, APK paths, Firebase app IDs
- Release to multiple flavors independently

✓ **APK Building**
- Automated Flutter APK build per flavor
- Configurable build output paths
- Build validation before distribution

✓ **Firebase Distribution**
- One-command distribution to Firebase App Distribution
- Customizable tester groups (testers, internal, external)
- Release notes auto-generated from git log
- Share links in output for easy distribution

✓ **Dry-Run Mode**
- Test version bumping, changelog, and tagging without building/distributing
- Perfect for validating setup

✓ **Environment Management**
- Auto-loads Firebase app IDs from `.env.dev`
- Interactive setup if config missing
- No hardcoded secrets in repo

## How It Works (Full Flow)

1. **Bump version** in `pubspec.yaml` (interactive or auto)
2. **Generate CHANGELOG.md** via `git-chglog`
3. **Generate release_note.txt** from git log since last tag
4. **Git commit** version changes
5. **Git tag** the release
6. **Build APK** for the flavor
7. **Distribute to Firebase App Distribution**

## Benefits

| Manual Process | fship |
|---|---|
| 15-20 min per release | 2-3 min per release |
| Multiple error-prone steps | Single command |
| Manual version tracking | Git-backed versions |
| Manual changelog maintenance | Auto-generated from commits |
| Easy to forget steps | Enforced workflow |
| Hard to track history | Full git history preserved |

## What It Does (Full Flow)

1. **Bump version** in `pubspec.yaml` (interactive or auto)
2. **Generate CHANGELOG.md** via `git-chglog`
3. **Generate release_note.txt** from git log since last tag
4. **Git commit** version changes
5. **Git tag** the release
6. **Build APK** for the flavor
7. **Distribute to Firebase App Distribution**

## Installation

**Via PyPI (Recommended)**
```bash
pip install fship
```

**From Source (Development)**
```bash
git clone https://github.com/MrShakila/F-ship.git
cd F-ship
pip install -e .
```

## Setup (One Time)

```bash
cd /path/to/your/flutter/project

# Copy default config
fship init

# Edit fship.yaml — set your Firebase app IDs, entry points, APK paths
vi fship.yaml

# Validate setup
fship validate
```

### fship.yaml Example

```yaml
flavors:
  qa:
    firebase_app_id_env: APPIDANDROID_QA
    entrypoint: lib/main_qa.dart
    apk_path: build/app/outputs/flutter-apk/app-qa-release.apk
    groups: testers

  prod:
    firebase_app_id_env: APPIDANDROID_PROD
    entrypoint: lib/main_prod.dart
    apk_path: build/app/outputs/flutter-apk/app-prod-release.apk
    groups: testers
```

## Usage

### Interactive Version Bump

```bash
fship release qa
# Current version: 1.2.3+45
# New version: 1.2.4+46
# [shows full release workflow with progress]
```

### Exact Version (Non-Interactive)

```bash
fship release qa --version 1.2.4+46
```

### Auto-Increment

```bash
fship release qa --bump patch    # 1.2.3+45 → 1.2.4+0
fship release qa --bump minor    # 1.2.3+45 → 1.3.0+0
fship release qa --bump major    # 1.2.3+45 → 2.0.0+0
```

### Dry Run (Skip Build & Distribution)

```bash
fship release qa --skip-build --skip-distribute
# Only bumps version, generates changelog, commits, tags
```

## Prerequisites

- Python 3.11+
- Flutter SDK
- Firebase CLI: `npm install -g firebase-tools`
- git-chglog: `brew install git-chglog` (macOS) or `npm install -g git-chglog`

## Environment Setup

**First run creates `.env.dev` template:**
```bash
fship release qa
# Creates .env.dev with placeholders, prompts you to fill in Android app IDs
```

Edit `.env.dev` with your Firebase Android app IDs:
```bash
# .env.dev (add to .gitignore)
APPIDANDROID_QA=1:123456:android:abcdef...
APPIDANDROID_UAT=1:345678:android:ghijkl...
APPIDANDROID_PROD=1:789012:android:mnopqr...
```

Get app IDs from Firebase Console > Project Settings > Your apps (Android).

fship automatically loads from `.env.dev` when you run `fship release`.

## Commands

```bash
fship release <flavor> [--version X.Y.Z+B] [--bump patch|minor|major] [--skip-build] [--skip-distribute]
fship init                         # Copy default fship.yaml
fship validate                     # Check tools and config
fship version                      # Show fship version
fship --help                       # Full help
```

## Troubleshooting

**"fship.yaml not found"**
```bash
fship init
vi fship.yaml  # customize
```

**"Firebase CLI not found"**
```bash
npm install -g firebase-tools
firebase login
```

**"git-chglog not found"**
```bash
brew install git-chglog
# or
npm install -g git-chglog
```

**"Commits/tags not created, but version was bumped"**
- Ensure you're in a git repo and have uncommitted changes allowed
- Check `git status`

## Development

```bash
git clone https://github.com/MrShakila/F-ship.git
cd F-ship
pip install -e .
fship --help
```
