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

# 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

# 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

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

# 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

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

# 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

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

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