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

Add 'history_tracking' to your INSTALLED_APPS:

INSTALLED_APPS = [
    ...
    'history_tracking',
]

Configure Redis connection in settings.py:

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

Run migrations:

python manage.py migrate history_tracking

Usage

Making Models Version-Controlled

Inherit from HistoricalModel:

from history_tracking.models import HistoricalModel

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

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

Working with Branches

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:

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:

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:

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:

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:

{% 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:

Performance Issues
- Check batch sizes
- Verify cache configuration
- Monitor database queries
- Review parallel processing settings
Cache Issues
- Verify Redis connection
- Check cache key conflicts
- Monitor cache hit rates
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.