191 lines
4.4 KiB
Markdown
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.
|