docling / COLLABORATIVE_WORKFLOW.md
levalencia's picture
Add enhanced sync script and collaborative workflow documentation
491bebc

Collaborative Workflow with Dual Repositories

This project is configured to sync with both Hugging Face and Azure DevOps repositories. This guide explains how to work collaboratively with your team.

Repository Configuration

  • Origin (Hugging Face): https://huggingface.co/spaces/levalencia/docling
  • Azure DevOps: https://element61.visualstudio.com/ZAS%20pati%C3%ABntvriendelijke%20brief/_git/streamlit_test_app_medicationlist

Recommended Workflow

For You (Project Owner)

Daily Workflow

  1. Before starting work: Run the enhanced sync script

    ./sync_repos_enhanced.sh
    
  2. Make your changes and commit them

    git add .
    git commit -m "Your commit message"
    
  3. Sync to both repositories

    ./sync_repos_enhanced.sh "Your commit message"
    

When Colleagues Have Made Changes

The enhanced script will automatically:

  • Fetch changes from both repositories
  • Merge any new commits
  • Handle conflicts gracefully
  • Push your changes to both repositories

For Your Colleagues

Option 1: Work on Azure DevOps Only (Recommended)

Your colleagues should:

  1. Clone from Azure DevOps

    git clone https://element61.visualstudio.com/ZAS%20pati%C3%ABntvriendelijke%20brief/_git/streamlit_test_app_medicationlist.git
    
  2. Make changes and push to Azure DevOps

    git add .
    git commit -m "Colleague's changes"
    git push origin main
    
  3. You'll sync their changes when you run the enhanced sync script

Option 2: Work on Both Repositories

If colleagues need access to both repositories:

  1. Clone your repository

    git clone https://huggingface.co/spaces/levalencia/docling.git
    
  2. Add Azure DevOps as a remote

    git remote add azure https://element61.visualstudio.com/ZAS%20pati%C3%ABntvriendelijke%20brief/_git/streamlit_test_app_medicationlist
    
  3. Use the enhanced sync script for their changes too

Conflict Resolution

Scenario 1: Colleagues Work on Azure DevOps

Timeline:
1. You make changes β†’ Push to both repos
2. Colleague makes changes β†’ Push to Azure only
3. You make more changes β†’ Try to sync

Result: Enhanced script will:
- Fetch from Azure DevOps
- Merge colleague's changes
- Push your merged changes to both repos

Scenario 2: Conflicts Occur

If there are merge conflicts:

  1. The script will stop and show you which files have conflicts
  2. Manually resolve conflicts in the conflicted files
  3. Add resolved files: git add .
  4. Commit: git commit -m "Resolve merge conflicts"
  5. Run the sync script again

Scenario 3: Force Push Needed

If you need to overwrite Azure DevOps changes:

./sync_repos_enhanced.sh "Your message" --force-azure

⚠️ Warning: Only use force push when you're sure you want to overwrite Azure DevOps changes!

Best Practices

Communication

  • Designate a primary repository: Decide which repo is the "source of truth"
  • Coordinate pushes: Let team know when you're about to sync
  • Use meaningful commit messages: Help track what changes were made

Workflow Tips

  • Always sync before starting work: Prevents conflicts
  • Test changes locally: Before pushing to either repository
  • Backup important work: Before force pushing
  • Use feature branches: For major changes to avoid conflicts

Repository Roles

  • Hugging Face: Primary development and deployment
  • Azure DevOps: Team collaboration and backup

Troubleshooting

Common Issues

"Push Rejected" Error

# Fetch and merge first
git fetch azure
git merge azure/main

# Then push
git push azure main

Merge Conflicts

# See conflicted files
git status

# Resolve conflicts manually, then
git add .
git commit -m "Resolve conflicts"

Force Push Safety

# Check what you're about to overwrite
git log azure/main --oneline -5

# Then force push if safe
./sync_repos_enhanced.sh "Your message" --force-azure

Emergency Recovery

If something goes wrong:

  1. Don't panic: Git keeps history
  2. Check both repositories: See which has the latest changes
  3. Reset if needed: git reset --hard <commit-hash>
  4. Re-apply changes: If you lost work, check git reflog

Scripts Available

  • sync_repos.sh: Basic sync script (original)
  • sync_repos_enhanced.sh: Enhanced script for collaborative work (recommended)

Team Guidelines

  1. Primary Developer (You): Use enhanced sync script, coordinate with team
  2. Colleagues: Work on Azure DevOps, communicate changes
  3. Everyone: Use meaningful commit messages, test before pushing
  4. Emergency: Contact primary developer before force pushing

This setup allows flexible collaboration while maintaining code integrity across both repositories.