nfoguard/.local/workflow.md

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