# 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.)

![Version Control Panel](../static/images/docs/version-control-panel.png)

### 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)