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

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:

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)

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

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

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

# 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

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

{% include "history_tracking/version_control_panel.html" %}

2. Branch Selection

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

3. Change History

<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

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

2. Conflict Resolution

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

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