feat: NFOGuard v1.7.2 - Complete media management system
Initial clean repository with full NFOGuard codebase: - Docker-based media file processing - Webhook integration for Radarr/Sonarr - NFO file management and organization - Emby/Jellyfin plugin integration - TMDB API integration for metadata - Smart episode and movie renaming - Comprehensive dual-repository development workflow Author: SBCrumb
This commit is contained in:
@@ -0,0 +1,221 @@
|
||||
# NFOGuard Development Workflow
|
||||
|
||||
## Overview
|
||||
NFOGuard uses a dual-repository system:
|
||||
- **Gitea (Private)**: `origin` - Development, testing, messy commits
|
||||
- **GitHub (Public)**: `github` - Clean releases, public testing
|
||||
|
||||
## Repository Setup
|
||||
```bash
|
||||
# Remotes should be configured as:
|
||||
origin gitea@192.168.253.221:jskala/NFOguard.git (fetch/push)
|
||||
github git@github.com:sbcrumb/nfoguard.git (fetch/push)
|
||||
```
|
||||
|
||||
## Daily Development Workflow
|
||||
|
||||
### 1. Local Development
|
||||
```bash
|
||||
# Work on dev branch (make as many commits as you want)
|
||||
git checkout dev
|
||||
# ... make changes, commit frequently ...
|
||||
git add .
|
||||
git commit -m "fix: whatever you're working on"
|
||||
|
||||
# Push to Gitea regularly for backup
|
||||
git push origin dev
|
||||
```
|
||||
|
||||
### 2. Feature Complete - Merge to Main
|
||||
```bash
|
||||
# When feature/fix is complete, merge to main
|
||||
git checkout main
|
||||
git merge dev
|
||||
|
||||
# Push to Gitea main
|
||||
git push origin main
|
||||
```
|
||||
|
||||
### 3. Prepare for GitHub Release
|
||||
|
||||
**Use the sync script for clean releases:**
|
||||
```bash
|
||||
# From main branch, run the sync script
|
||||
./sync-to-github.sh
|
||||
|
||||
# Choose Option 3: "Create clean release branch for GitHub PR (RECOMMENDED)"
|
||||
# This will:
|
||||
# 1. Increment version (patch/minor/major)
|
||||
# 2. Create clean release-vX.X.X branch from GitHub main
|
||||
# 3. Copy your changes with single clean commit
|
||||
# 4. Push to GitHub automatically
|
||||
```
|
||||
|
||||
**The script will output:**
|
||||
```
|
||||
🔗 Create PR at: https://github.com/sbcrumb/nfoguard/pull/new/release-v1.7.0
|
||||
📝 PR will be: release-v1.7.0 → main (clean, single commit)
|
||||
```
|
||||
|
||||
### 4. GitHub Testing and Release
|
||||
```bash
|
||||
# 1. Create PR: release-vX.X.X → main on GitHub
|
||||
# 2. Test the release branch thoroughly
|
||||
# 3. Merge when satisfied (squash merge will be available)
|
||||
```
|
||||
|
||||
## Manual Process (If Script Unavailable)
|
||||
|
||||
### Emergency Manual Release
|
||||
If the sync script isn't available, here's the manual process:
|
||||
|
||||
```bash
|
||||
# 1. Fetch latest GitHub main
|
||||
git fetch github
|
||||
|
||||
# 2. Create clean release branch
|
||||
git checkout -b release-v1.7.0 github/main
|
||||
|
||||
# 3. Copy key files from your local main
|
||||
git checkout main -- VERSION Dockerfile core/nfo_manager.py nfoguard.py .env.template .env.secrets.template .gitea/
|
||||
|
||||
# 4. Increment version manually
|
||||
echo "1.7.0" > VERSION
|
||||
|
||||
# 5. Commit and push
|
||||
git add .
|
||||
git commit -m "feat: Release v1.7.0 - [describe key changes]"
|
||||
git push github release-v1.7.0
|
||||
|
||||
# 6. Create PR on GitHub: release-v1.7.0 → main
|
||||
```
|
||||
|
||||
## Important Files and Their Purpose
|
||||
|
||||
### Local-Only Files (Never Commit to Gitea/GitHub)
|
||||
- `sync-to-github.sh` - GitHub sync automation
|
||||
- `.local/` directory - Local documentation and notes
|
||||
- `.env.secrets` - API keys and passwords
|
||||
|
||||
### Repository-Specific Files
|
||||
- `.gitea/workflows/` - Gitea CI/CD (ignored by GitHub)
|
||||
- `.github/workflows/` - GitHub CI/CD (ignored by Gitea)
|
||||
|
||||
### Shared Files
|
||||
- Core application code
|
||||
- Dockerfile
|
||||
- Configuration templates
|
||||
- VERSION file
|
||||
|
||||
## Version Management
|
||||
|
||||
### Semantic Versioning
|
||||
- **Patch (X.Y.Z+1)**: Bug fixes, small updates
|
||||
- **Minor (X.Y+1.0)**: New features, enhancements
|
||||
- **Major (X+1.0.0)**: Breaking changes, major releases
|
||||
|
||||
### Version Identification
|
||||
- **Local Gitea builds**: `1.7.0-dev-gitea`
|
||||
- **GitHub releases**: `1.7.0`
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### "Messy Commit History" in GitHub PRs
|
||||
**Problem**: Local dev has 20+ commits that make GitHub PRs hard to review
|
||||
**Solution**: Always use sync script Option 3 to create clean release branches
|
||||
|
||||
### "No Common History" Error
|
||||
**Problem**: GitHub and local repos have different histories
|
||||
**Solution**: Use the clean release branch workflow (creates branches from GitHub main)
|
||||
|
||||
### "Sync Script Not Working"
|
||||
**Fallback**: Use the manual process outlined above
|
||||
|
||||
### Local Branch "Ahead by X Commits"
|
||||
**Normal**: Your local dev is ahead of Gitea dev - just push when ready
|
||||
```bash
|
||||
git push origin dev # Sync to Gitea
|
||||
```
|
||||
|
||||
## Branch Strategy
|
||||
|
||||
### Local Branches
|
||||
- `dev` - Active development (tracks origin/dev)
|
||||
- `main` - Stable local code (tracks origin/main)
|
||||
|
||||
### GitHub Branches
|
||||
- `release-vX.X.X` - Clean release branches (created by sync script)
|
||||
- `main` - Public stable releases
|
||||
- `dev` - Optional testing branch
|
||||
|
||||
### Gitea Branches
|
||||
- `dev` - Development history (all commits)
|
||||
- `main` - Feature-complete code (merged from dev)
|
||||
|
||||
## CI/CD Behavior
|
||||
|
||||
### Gitea Workflows
|
||||
- Build locally only (no Docker Hub)
|
||||
- Version shows as "X.X.X-dev-gitea"
|
||||
- Triggered on dev/main pushes
|
||||
|
||||
### GitHub Workflows
|
||||
- Build to GitHub Container Registry
|
||||
- Version shows as "X.X.X" (clean)
|
||||
- Triggered on main pushes
|
||||
|
||||
## Emergency Procedures
|
||||
|
||||
### If Sync Script is Lost
|
||||
1. Recreate from this workflow document
|
||||
2. Use manual process for immediate needs
|
||||
3. Script should be in `.local/` directory and ignored by git
|
||||
|
||||
### If GitHub Repo Gets Corrupted
|
||||
1. Force push clean main from Gitea
|
||||
2. Recreate release branches as needed
|
||||
3. Your code is safe in Gitea
|
||||
|
||||
### If Gitea Goes Down
|
||||
1. Continue development locally
|
||||
2. Push to GitHub dev branch for backup
|
||||
3. Sync back to Gitea when restored
|
||||
|
||||
## Success Indicators
|
||||
|
||||
### Good Workflow Signs
|
||||
- ✅ GitHub PRs have 1-3 clean commits
|
||||
- ✅ Local history is detailed and preserved
|
||||
- ✅ Version numbers increment properly
|
||||
- ✅ CI/CD builds succeed on both platforms
|
||||
|
||||
### Warning Signs
|
||||
- ❌ GitHub PRs have 20+ messy commits
|
||||
- ❌ "No common history" errors
|
||||
- ❌ Version numbers out of sync
|
||||
- ❌ Sync script getting committed to repos
|
||||
|
||||
## Quick Reference Commands
|
||||
|
||||
```bash
|
||||
# Daily development
|
||||
git checkout dev && git pull origin dev
|
||||
# ... work ...
|
||||
git add . && git commit -m "fix: description"
|
||||
git push origin dev
|
||||
|
||||
# Complete feature
|
||||
git checkout main && git merge dev && git push origin main
|
||||
|
||||
# Release to GitHub
|
||||
./sync-to-github.sh # Choose option 3
|
||||
|
||||
# Check status
|
||||
git status
|
||||
git log --oneline -5
|
||||
git remote -v
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**Remember**: The sync script Option 3 is your best friend for clean GitHub releases!
|
||||
Reference in New Issue
Block a user