# Version Control System

## Overview
A comprehensive version control system for Django models that provides branching, merging, and change tracking capabilities with optimized performance through batch processing and caching.

## Requirements

### System Requirements
- Python 3.8+
- Django 4.0+
- Redis 6.0+ (for caching)
- PostgreSQL 12+ (recommended for database)

### Python Dependencies
```
django-simple-history>=3.0.0
redis>=4.0.0
```

## Installation

1. Add 'history_tracking' to your INSTALLED_APPS:
```python
INSTALLED_APPS = [
    ...
    'history_tracking',
]
```

2. Configure Redis connection in settings.py:
```python
# Uses existing Redis configuration if available
CACHES = {
    "default": {
        "BACKEND": "django.core.cache.backends.redis.RedisCache",
        "LOCATION": "redis://127.0.0.1:6379/1",  # Adjust as needed
    }
}

# Version control specific settings
VERSION_CONTROL = {
    'CACHE_PREFIX': 'vc_',  # Prefix for cache keys
    'BATCH_SIZE': 100,      # Default batch size for operations
    'MAX_WORKERS': 4,       # Maximum parallel workers
    'CACHE_DURATIONS': {    # Cache durations in seconds
        'BRANCH': 3600,     # 1 hour
        'CHANGE': 1800,     # 30 minutes
        'HISTORY': 86400,   # 24 hours
    }
}
```

3. Run migrations:
```bash
python manage.py migrate history_tracking
```

## Usage

### Making Models Version-Controlled

1. Inherit from HistoricalModel:
```python
from history_tracking.models import HistoricalModel

class YourModel(HistoricalModel):
    name = models.CharField(max_length=255)
    description = models.TextField()
```

2. The model will automatically track:
   - All field changes
   - Who made changes
   - When changes were made
   - Which branch changes were made in

### Working with Branches

```python
from history_tracking.models import VersionBranch

# Create a new branch
branch = VersionBranch.objects.create(
    name="feature/new-content",
    metadata={"type": "feature"}
)

# Make changes in branch context
from history_tracking.context_processors import branch_context

with branch_context(branch):
    your_model.save()  # Changes are tracked in the branch
```

### Batch Operations

For handling multiple changes efficiently:

```python
from history_tracking.batch import BatchOperation

# Create batch operation
batch = BatchOperation(max_workers=4)

# Add changes to batch
for item in items:
    batch.add_change(item, {'field': 'new_value'})

# Process changes (parallel or sequential)
results = batch.commit(parallel=True)
```

### Using the Queue System

For large-scale operations:

```python
from history_tracking.batch import VersionControlQueue

# Create queue with custom batch size
queue = VersionControlQueue(batch_size=100)

# Queue changes
for item in large_dataset:
    queue.queue_change(item, {'field': 'new_value'})

# Process queue
results = queue.process_queue(parallel=True)
```

## Cache Management

The system automatically caches:
- Branch information
- Change details
- Version history

Cache invalidation is handled automatically, but you can manually invalidate:

```python
from history_tracking.caching import VersionHistoryCache

# Invalidate specific caches
VersionHistoryCache.invalidate_branch(branch_id)
VersionHistoryCache.invalidate_history(content_type_id, object_id)

# Invalidate all version control caches
VersionHistoryCache.invalidate_all()
```

## Monitoring

The system includes built-in monitoring:

```python
from history_tracking.monitoring import VersionControlMetrics

# Collect system metrics
VersionControlMetrics.collect_system_metrics()
VersionControlMetrics.collect_performance_metrics()
```

Metrics are logged and can be viewed:
- In application logs
- Through the Django admin interface
- Via monitoring endpoints (if configured)

## Performance Considerations

The system is optimized for:
- Batch processing of changes
- Efficient caching of frequently accessed data
- Parallel processing capabilities
- Minimal database queries

For large-scale operations:
- Use batch processing
- Enable parallel processing when appropriate
- Configure cache durations based on your needs
- Monitor performance metrics

## Security

The system integrates with Django's authentication and permissions:
- All changes are tracked with user information
- Branch access can be controlled
- Merge operations can require approval

## Templates

The system includes template tags for displaying version control information:

```html
{% load version_control_tags %}

{% version_status object %}
{% branch_selector %}
{% history_list object %}
```

## API Endpoints

Documentation for API endpoints can be found in `docs/version_control_api.md`.

## Database Considerations

The system uses your existing Django database configuration and creates these main tables:
- history_tracking_versionbranch
- history_tracking_changeset
- history_tracking_versiontag
- history_tracking_commentthread

Plus historical tables for each tracked model.

## Troubleshooting

Common issues and solutions:

1. Performance Issues
   - Check batch sizes
   - Verify cache configuration
   - Monitor database queries
   - Review parallel processing settings

2. Cache Issues
   - Verify Redis connection
   - Check cache key conflicts
   - Monitor cache hit rates

3. Database Issues
   - Check indexing
   - Monitor query performance
   - Review database connection pool settings

## Contributing

Contributions are welcome! Please read our contributing guidelines and submit pull requests.

## License

This project is licensed under the MIT License - see the LICENSE file for details.