thrillwiki_django_no_react/docs/version_control_api.md

# Version Control System API Documentation

## Overview
The version control system provides a comprehensive API for managing content versioning, branching, and merging across different models in the system.

## Core Models

### VersionBranch
Represents a branch in the version control system.

```python
class VersionBranch:
    name: str           # Branch name (unique)
    metadata: JSONField # Branch metadata
    is_active: bool    # Branch status
    created_at: datetime
    updated_at: datetime
```

### ChangeSet
Represents a set of changes to a versioned object.

```python
class ChangeSet:
    branch: ForeignKey      # Reference to VersionBranch
    content_type: ForeignKey # ContentType of the changed object
    object_id: int         # ID of the changed object
    data: JSONField        # Change data
    status: str           # Status (pending, applied, conflict)
    created_at: datetime
    applied_at: datetime
```

## API Endpoints

### Branch Management

#### Create Branch
```http
POST /api/v1/version-control/branches/
```

Request body:
```json
{
    "name": "feature/new-branch",
    "metadata": {
        "type": "feature",
        "description": "New feature branch"
    }
}
```

Response:
```json
{
    "id": 1,
    "name": "feature/new-branch",
    "metadata": {
        "type": "feature",
        "description": "New feature branch"
    },
    "is_active": true,
    "created_at": "2025-02-07T09:00:00Z"
}
```

#### Switch Branch
```http
POST /api/v1/version-control/branches/{branch_id}/switch/
```

Response:
```json
{
    "status": "success",
    "branch": {
        "id": 1,
        "name": "feature/new-branch"
    }
}
```

### Change Management

#### Create Change
```http
POST /api/v1/version-control/changes/
```

Request body:
```json
{
    "branch_id": 1,
    "content_type": "parks.park",
    "object_id": 123,
    "data": {
        "name": "Updated Name",
        "description": "Updated description"
    }
}
```

Response:
```json
{
    "id": 1,
    "branch": 1,
    "status": "pending",
    "created_at": "2025-02-07T09:05:00Z"
}
```

#### Apply Change
```http
POST /api/v1/version-control/changes/{change_id}/apply/
```

Response:
```json
{
    "status": "success",
    "change": {
        "id": 1,
        "status": "applied",
        "applied_at": "2025-02-07T09:06:00Z"
    }
}
```

### Merge Operations

#### Merge Branch
```http
POST /api/v1/version-control/branches/{source_id}/merge/
```

Request body:
```json
{
    "target_branch_id": 2
}
```

Response:
```json
{
    "status": "success",
    "conflicts": []
}
```

#### Resolve Conflicts
```http
POST /api/v1/version-control/merge/resolve/
```

Request body:
```json
{
    "merge_id": 1,
    "resolutions": [
        {
            "field": "name",
            "value": "Resolved Name"
        }
    ]
}
```

Response:
```json
{
    "status": "success",
    "merge": {
        "id": 1,
        "status": "completed"
    }
}
```

## Model Integration

### Adding Version Control to Models

To make a model version-controlled, inherit from `HistoricalModel`:

```python
from history_tracking.models import HistoricalModel

class YourModel(HistoricalModel):
    name = models.CharField(max_length=255)
    
    def save(self, *args, **kwargs):
        # Get the branch from context
        current_branch = get_current_branch()
        
        if current_branch:
            # Save in branch context
            super().save(*args, **kwargs)
        else:
            # Save in main branch
            with ChangesetContextManager(branch=main_branch):
                super().save(*args, **kwargs)
```

### Version Control Methods

Each versioned model has access to these methods:

#### get_version_info()
Returns version control information for the object:
```python
info = model.get_version_info()
# Returns:
{
    'latest_changes': [ChangeSet],
    'active_branches': [VersionBranch],
    'current_branch': VersionBranch,
    'total_changes': int
}
```

#### get_changes()
Returns all changes for the object:
```python
changes = model.get_changes()
# Returns QuerySet of ChangeSet objects
```

## JavaScript Integration

### Version Control UI

Initialize version control UI:
```javascript
import { initVersionControl } from 'version-control.js';

initVersionControl({
    container: '#version-control-panel',
    onChange: (branch) => {
        // Handle branch change
    }
});
```

### Branch Operations

Switch branches:
```javascript
import { switchBranch } from 'version-control.js';

switchBranch(branchId).then(response => {
    if (response.status === 'success') {
        // Handle successful branch switch
    }
});
```

### Merge Operations

Handle merge conflicts:
```javascript
import { handleMergeConflicts } from 'version-control.js';

handleMergeConflicts(conflicts).then(resolutions => {
    // Handle conflict resolutions
});
```

## Error Handling

The API uses standard HTTP status codes:

- 200: Success
- 400: Bad Request
- 401: Unauthorized
- 403: Forbidden
- 404: Not Found
- 409: Conflict (merge conflicts)
- 500: Internal Server Error

Error responses include detailed information:
```json
{
    "status": "error",
    "message": "Detailed error message",
    "code": "ERROR_CODE",
    "details": {
        // Additional error details
    }
}
```

## Rate Limiting

API endpoints are rate-limited:
- Authenticated users: 100 requests per minute
- Anonymous users: 20 requests per minute

Rate limit headers are included in responses:
```http
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1623456789
```

## Monitoring

Monitor version control operations through the monitoring dashboard:
```http
GET /version-control/monitoring/
```

The dashboard provides real-time metrics for:
- Branch operations
- Merge success rates
- Change tracking overhead
- Error rates
- System health