jellyflood/DEVELOPMENT.md

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:

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

Example:

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

   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

   # 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

   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:

# 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.