jellyflood/DEVELOPMENT.md

191 lines
4.4 KiB
Markdown

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