thrillwiki_django_no_react/docs/version_control_user_guide.md

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
• Technical Documentation
• Video Tutorials
• Community Forums