# ThrillWiki Version Control System

## Overview
The ThrillWiki Version Control System (VCS) provides comprehensive version tracking, branching, and merging capabilities for all content in the system. It builds upon django-simple-history while adding powerful versioning features.

## Features
- Full version history tracking
- Branch-based development
- Version tagging
- Merge operations with conflict resolution
- Real-time collaborative editing
- Automatic change tracking

## Model Integration

### Making Models Version-Controlled
To add version control to any model, inherit from `HistoricalModel`:

```python
from history_tracking.models import HistoricalModel

class YourModel(HistoricalModel):
    # Your model fields here
    name = models.CharField(max_length=255)
    
    class Meta:
        # Your meta options
```

This automatically provides:
- Full version history
- Change tracking
- Branch support
- Merge capabilities

### Example Integration (from parks/models.py)
```python
from history_tracking.models import HistoricalModel

class Park(HistoricalModel):
    name = models.CharField(max_length=255)
    description = models.TextField()
    
    def save(self, *args, **kwargs):
        # Changes will be automatically tracked
        super().save(*args, **kwargs)
```

## Usage Guide

### Basic Version Control Operations

1. Creating a Branch
```python
from history_tracking.managers import BranchManager

# Create a new feature branch
branch_manager = BranchManager()
feature_branch = branch_manager.create_branch(
    name="feature/new-park-details",
    user=request.user
)
```

2. Recording Changes
```python
from history_tracking.signals import ChangesetContextManager

# Making changes in a specific branch
with ChangesetContextManager(branch=feature_branch, user=request.user):
    park = Park.objects.get(id=1)
    park.description = "Updated description"
    park.save()  # Change is automatically tracked in the branch
```

3. Merging Changes
```python
# Merge feature branch back to main
success, conflicts = branch_manager.merge_branches(
    source=feature_branch,
    target=main_branch,
    user=request.user
)

if not success:
    # Handle merge conflicts
    for conflict in conflicts:
        # Resolve conflicts through UI or programmatically
        pass
```

4. Working with Tags
```python
from history_tracking.models import VersionTag

# Tag a specific version
VersionTag.objects.create(
    name="v1.0.0",
    branch=main_branch,
    content_type=ContentType.objects.get_for_model(park),
    object_id=park.id,
    created_by=user
)
```

## UI Integration

### HTMX Components
The system provides HTMX-powered components for real-time version control:

1. Version Control Panel
```html
{% include "history_tracking/version_control_panel.html" %}
```

2. Branch Selection
```html
<div hx-get="{% url 'history:branch-list' %}"
     hx-trigger="load, branch-updated from:body">
</div>
```

3. Change History
```html
<div hx-get="{% url 'history:history-view' %}?branch={{ branch.name }}"
     hx-trigger="load, branch-selected from:body">
</div>
```

## Best Practices

1. Branch Management
- Create feature branches for significant changes
- Use descriptive branch names (e.g., "feature/new-park-system")
- Clean up merged branches
- Regularly sync with main branch

2. Change Tracking
- Make atomic, related changes
- Provide clear change descriptions
- Group related changes in a single changeset
- Review changes before merging

3. Conflict Resolution
- Resolve conflicts promptly
- Communicate with team members about overlapping changes
- Test after resolving conflicts
- Document resolution decisions

4. Performance
- Use changesets for bulk operations
- Index frequently queried fields
- Clean up old branches and tags
- Monitor system performance

## Error Handling

1. Common Issues
```python
try:
    branch_manager.merge_branches(source, target)
except ValidationError as e:
    # Handle validation errors
except MergeConflict as e:
    # Handle merge conflicts
```

2. Conflict Resolution
```python
from history_tracking.utils import resolve_conflicts

resolved = resolve_conflicts(
    source_branch=source,
    target_branch=target,
    resolutions={
        'conflict_id': 'resolution_type',  # 'source', 'target', or 'manual'
    },
    manual_resolutions={
        'conflict_id': 'manual resolution content'
    },
    user=request.user
)
```

## System Maintenance

1. Regular Tasks
- Clean up old branches
- Archive old versions
- Verify data integrity
- Monitor system health

2. Monitoring
```python
from history_tracking.utils import get_system_metrics

metrics = get_system_metrics()
# Check branch counts, merge success rates, etc.
```

## Security Considerations

1. Access Control
- All VCS operations require authentication
- Branch operations are logged
- Merge operations require proper permissions
- Changes are tracked with user attribution

2. Data Protection
- Historical data is preserved
- Audit logs are maintained
- Sensitive data is handled securely
- Backups include version history

## Support and Troubleshooting

For issues or questions:
1. Check the logs for detailed error messages
2. Review the conflict resolution documentation
3. Verify branch and change permissions
4. Contact the development team for assistance

## Contributing
When contributing to the VCS:
1. Follow the established branching pattern
2. Document significant changes
3. Add tests for new features
4. Update technical documentation