COLLABORATIVE_WORKFLOW.md

# 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
   ```bash
   ./sync_repos_enhanced.sh
   ```

2. **Make your changes** and commit them
   ```bash
   git add .
   git commit -m "Your commit message"
   ```

3. **Sync to both repositories**
   ```bash
   ./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
   ```bash
   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
   ```bash
   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
   ```bash
   git clone https://huggingface.co/spaces/levalencia/docling.git
   ```

2. Add Azure DevOps as a remote
   ```bash
   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:
```bash
./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
```bash
# Fetch and merge first
git fetch azure
git merge azure/main

# Then push
git push azure main
```

#### Merge Conflicts
```bash
# See conflicted files
git status

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

#### Force Push Safety
```bash
# 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.