mirror of
https://github.com/pacnpal/thrillwiki_django_no_react.git
synced 2025-12-20 11:51:10 -05:00
Revert "Add version control system functionality with branch management, history tracking, and merge operations"
This reverts commit f3d28817a5.
This commit is contained in:
pacnpal
@@ -1,320 +0,0 @@
|
||||
# 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
|
||||
@@ -1,184 +0,0 @@
|
||||
# Version Control User Guide
|
||||
|
||||
## Introduction
|
||||
The version control system allows you to track changes, create branches, and merge content updates across ThrillWiki. This guide explains how to use the version control features effectively.
|
||||
|
||||
## Basic Concepts
|
||||
|
||||
### Branches
|
||||
A branch is a separate line of development that allows you to make changes without affecting the main content. Think of it like a draft version of your content.
|
||||
|
||||
- **Main Branch**: The default branch containing the live, published content
|
||||
- **Feature Branches**: Temporary branches for developing new content or making significant changes
|
||||
- **Active Branch**: The branch you're currently working on
|
||||
|
||||
### Changes
|
||||
Changes represent modifications to content:
|
||||
- Adding new information
|
||||
- Updating existing content
|
||||
- Removing outdated content
|
||||
|
||||
### Merging
|
||||
Merging combines changes from one branch into another, typically from a feature branch back into the main branch.
|
||||
|
||||
## Using Version Control
|
||||
|
||||
### 1. Version Control Panel
|
||||
The version control panel appears at the top of editable pages and shows:
|
||||
- Current branch
|
||||
- Branch selector
|
||||
- Action buttons (Create Branch, Merge, etc.)
|
||||
|
||||
|
||||
|
||||
### 2. Creating a Branch
|
||||
1. Click "Create Branch" in the version control panel
|
||||
2. Enter a branch name (e.g., "update-park-details")
|
||||
3. Add an optional description
|
||||
4. Click "Create"
|
||||
|
||||
Branch naming conventions:
|
||||
- Use lowercase letters
|
||||
- Separate words with hyphens
|
||||
- Be descriptive (e.g., "add-new-rides", "update-park-history")
|
||||
|
||||
### 3. Switching Branches
|
||||
1. Open the branch selector in the version control panel
|
||||
2. Select the desired branch
|
||||
3. Click "Switch Branch"
|
||||
|
||||
Note: You'll see a warning if you have unsaved changes.
|
||||
|
||||
### 4. Making Changes
|
||||
1. Ensure you're on the correct branch
|
||||
2. Edit content normally
|
||||
3. Save changes
|
||||
4. Changes are tracked automatically
|
||||
|
||||
The version control panel shows:
|
||||
- Number of changes
|
||||
- Last update time
|
||||
- Change status
|
||||
|
||||
### 5. Viewing History
|
||||
1. Click "History" in the version control panel
|
||||
2. See a list of changes with:
|
||||
- Timestamp
|
||||
- Author
|
||||
- Description
|
||||
- Branch
|
||||
3. Click any change to see details
|
||||
|
||||
### 6. Merging Changes
|
||||
1. Switch to the target branch (usually main)
|
||||
2. Click "Merge" in the version control panel
|
||||
3. Select the source branch
|
||||
4. Review changes
|
||||
5. Click "Merge Changes"
|
||||
|
||||
### 7. Handling Conflicts
|
||||
If conflicts occur during merging:
|
||||
1. The conflict resolution dialog appears
|
||||
2. Review conflicting changes
|
||||
3. Choose which version to keep or combine them
|
||||
4. Click "Resolve Conflicts"
|
||||
5. Complete the merge
|
||||
|
||||
## Best Practices
|
||||
|
||||
### When to Create a Branch
|
||||
Create a new branch when:
|
||||
- Making substantial content updates
|
||||
- Adding new sections
|
||||
- Reorganizing information
|
||||
- Testing new features
|
||||
|
||||
### Branch Management
|
||||
- Keep branches focused on specific tasks
|
||||
- Delete branches after merging
|
||||
- Regular merge changes from main to stay current
|
||||
- Use descriptive branch names
|
||||
|
||||
### Change Management
|
||||
- Make atomic, related changes
|
||||
- Write clear change descriptions
|
||||
- Review changes before merging
|
||||
- Test content in preview mode
|
||||
|
||||
### Collaboration
|
||||
- Communicate branch purpose to team members
|
||||
- Coordinate on shared branches
|
||||
- Review changes before merging
|
||||
- Resolve conflicts together when needed
|
||||
|
||||
## Common Tasks
|
||||
|
||||
### Updating a Park Page
|
||||
1. Create a branch (e.g., "update-park-info")
|
||||
2. Make changes to park information
|
||||
3. Preview changes
|
||||
4. Merge back to main when ready
|
||||
|
||||
### Adding New Rides
|
||||
1. Create a branch (e.g., "add-new-rides-2025")
|
||||
2. Add ride information
|
||||
3. Add photos and details
|
||||
4. Review and merge
|
||||
|
||||
### Content Reorganization
|
||||
1. Create a branch (e.g., "reorganize-sections")
|
||||
2. Rearrange content
|
||||
3. Update navigation
|
||||
4. Test thoroughly
|
||||
5. Merge changes
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Common Issues
|
||||
|
||||
#### Unable to Create Branch
|
||||
- Check permissions
|
||||
- Verify branch name is valid
|
||||
- Ensure no conflicts with existing branches
|
||||
|
||||
#### Merge Conflicts
|
||||
1. Don't panic! Conflicts are normal
|
||||
2. Review both versions carefully
|
||||
3. Choose the best content
|
||||
4. Test after resolving
|
||||
|
||||
#### Lost Changes
|
||||
1. Check branch history
|
||||
2. Review recent changes
|
||||
3. Contact administrator if needed
|
||||
|
||||
### Getting Help
|
||||
- Click the "Help" button in the version control panel
|
||||
- Contact administrators for complex issues
|
||||
- Check documentation for guidance
|
||||
|
||||
## Version Control Status Icons
|
||||
|
||||
| Icon | Meaning |
|
||||
|------|---------|
|
||||
| 🟢 | Current branch |
|
||||
| 🔄 | Pending changes |
|
||||
| ⚠️ | Merge conflicts |
|
||||
| ✅ | Successfully merged |
|
||||
| 🔒 | Protected branch |
|
||||
|
||||
## Keyboard Shortcuts
|
||||
|
||||
| Action | Shortcut |
|
||||
|--------|----------|
|
||||
| Switch Branch | Ctrl/Cmd + B |
|
||||
| Create Branch | Ctrl/Cmd + Shift + B |
|
||||
| View History | Ctrl/Cmd + H |
|
||||
| Merge Branch | Ctrl/Cmd + M |
|
||||
| Save Changes | Ctrl/Cmd + S |
|
||||
|
||||
## Additional Resources
|
||||
- [API Documentation](version_control_api.md)
|
||||
- [Technical Documentation](technical_architecture.md)
|
||||
- [Video Tutorials](https://wiki.thrillwiki.com/tutorials)
|
||||
- [Community Forums](https://community.thrillwiki.com)
|
||||
Reference in New Issue
Block a user