Add version control context processor and integrate map functionality with dedicated JavaScript

memory-bank/features/version-control/README.md

@@ -0,0 +1,228 @@
+# 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