# jellyflood Development Practices

## Issue-Driven Development

All work on jellyflood follows an **issue-driven workflow**. Every feature, bug fix, or improvement must have a corresponding issue on Gitea before work begins.

### Creating Issues

Use the provided script to create issues:

```bash
scripts/create-issue.sh "jellyflood-X: Title" "Description" "feature|bug"
```

**Example:**

```bash
scripts/create-issue.sh \
  "jellyflood-8: Add EPG support for Xtream Live TV" \
  "Implement EPG (Electronic Program Guide) for Xtream Live TV channels.

## Requirements
- [ ] Fetch EPG data from Xtream API
- [ ] Display EPG in channel list
- [ ] Show current/next program info

## Dependencies
- Requires jellyflood-3 (XtreamAPIClient)" \
  "feature"
```

**Issue Naming Convention:**
- Format: `jellyflood-X: Title`
- Where `X` is the next sequential number
- Use descriptive titles

**Labels:**
- `feature` - New functionality
- `bug` - Bug fixes

### Prerequisites

The `create-issue.sh` script requires:
- `GITEA_API_TOKEN` environment variable set in `~/.zshrc`
- Get your token at: https://git.ashik.se/user/settings/applications

## Branching Strategy

### Branch Naming

All work-in-progress code uses the branch naming pattern:

```
jellyflood-<ticket_num>/wip<iteration>
```

**Examples:**
- `jellyflood-1/wip0` - First WIP for issue #1
- `jellyflood-1/wip1` - Second iteration/WIP for issue #1
- `jellyflood-8/wip0` - First WIP for issue #8

### Workflow

1. **Create Issue** (using `create-issue.sh`)
2. **Create WIP Branch**
   ```bash
   git checkout main
   git pull mine main
   git checkout -b jellyflood-X/wip0
   ```

3. **Work on Changes**
   - Make commits with descriptive messages
   - Reference issue number in commits: `Closes: jellyflood-X` or `Related: jellyflood-X`

4. **Build and Test Locally**
   ```bash
   # Always build before pushing
   xcodebuild -project jellyflood.xcodeproj \
     -scheme "jellyflood tvOS" \
     -destination "platform=tvOS Simulator,id=16A71179-729D-4F1B-8698-8371F137025B" \
     -configuration Debug \
     build
   ```

5. **Push WIP Branch**
   ```bash
   git push mine jellyflood-X/wip0 -u
   ```

6. **Do NOT Push to Main Directly**
   - Never push directly to `main` branch
   - Never use `git add -A` (review files individually)
   - All integration happens via CI (see below)

## Continuous Integration (Pending)

> **Status:** CI/CD toolchain pending setup

Once CI is configured with a dedicated Mac runner (using Tailscale):

1. **Create Pull Request** on Gitea
   - From: `jellyflood-X/wip0`
   - To: `main`

2. **CI Pipeline Runs**
   - Build verification
   - Tests execution
   - Code quality checks

3. **Merge After CI Passes**
   - Only merge if all CI checks pass
   - Squash or merge commits as appropriate

## Git Commit Guidelines

### Commit Message Format

```
Short summary (50 chars or less)

Detailed description if needed:
- What changed
- Why it changed
- Any breaking changes

Closes: jellyflood-X
Related: jellyflood-Y, jellyflood-Z

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
```

### File Staging

**NEVER use `git add -A` or `git add .`**

Always add files individually after review:

```bash
# Check what changed
git status

# Review each file
git diff path/to/file

# Add individually
git add path/to/file1
git add path/to/file2

# Verify staged changes
git status
```

## Code Review Checklist

Before pushing to WIP branch:

- [ ] Issue created on Gitea
- [ ] Branch follows naming: `jellyflood-X/wip0`
- [ ] Code builds without errors
- [ ] Files added individually (no `git add -A`)
- [ ] Commit message references issue
- [ ] No API tokens or secrets in code
- [ ] No build artifacts committed

## Issue Tracking

View all issues at: https://git.ashik.se/ashikk/jellyflood/issues

**Current Issues:**
- jellyflood-1: Xtream Player
- jellyflood-2: Dual Provider Architecture
- jellyflood-3: XtreamAPIClient VOD and Series support
- jellyflood-4: Multi-provider account switching
- jellyflood-5: Xtream channels in Media tab (bug)
- jellyflood-6: Xtream tab UI sections
- jellyflood-7: Provider selection in login flow

## Self-Hosted Infrastructure

jellyflood follows a **fully self-hosted ideology**:

- **Git Repository:** Self-hosted Gitea at git.ashik.se
- **Issue Tracking:** Gitea Issues
- **CI/CD (Pending):** Dedicated Mac runner via Tailscale
- **Media Server:** Self-hosted Jellyfin

All development infrastructure is under your control.