Version Control 101: Track Every Change Like a Pro

The complete guide to Gameframe's version control system

Read Time: 18 minutes

§Introduction: The Question That Costs Studios Millions#

Every game studio has experienced this moment:

"Wait, when did we change player health to 150?"

"Who removed the shield mechanic? And why?"

"Can we go back to last week's ability design?"

"Which version of this doc did the programmer implement?"

These questions seem small. But multiply them across a team, across months of development, and they become a massive productivity drain.

A 20-person studio loses an estimated $200,000+ annually to documentation confusion—rework from implementing wrong specs, meeting time spent clarifying "what's current," and the invisible cost of decisions made from outdated information.

Version control eliminates these questions. This guide teaches you how.

§Part 1: The Mental Model#

What Is Version Control, Really?#

If you've worked with programmers, you've heard of Git. Every line of code has a history. Developers can see exactly what changed, when, by whom, and why. They can experiment safely. They can undo mistakes instantly.

Version control for design docs is the same concept applied to your work.

Every document becomes a timeline of changes. Instead of a file that gets overwritten, you have a history you add to. Every save is a checkpoint. Every checkpoint is accessible forever.

Versions vs. Saves#

In Google Docs or Notion, you "save" a document. The new content replaces the old. There's some version history buried in menus, but it's vague—"edited 2 hours ago by Sarah."

In Gameframe, you "create a version." The new content is added as v2 (or v3, v4, etc.). The old versions remain. Both are accessible. Both are comparable.

Key insight: Stop thinking "save." Start thinking "create checkpoint."

Why This Matters for Games#

Game development is uniquely iterative:

• —Balance changes daily based on playtesting
• —Features get cut, then un-cut, then cut again
• —Multiple people touch the same systems
• —Decisions made months ago affect today's implementation

Without version control, you're constantly asking "what's current?" With version control, the answer is always one click away.

§Part 2: Understanding Versions in Gameframe#

Anatomy of a Version#

Every version in Gameframe contains:

Creating New Versions#

Every time you edit and save a document, you create a new version. The workflow:

1. 1.Open the document
2. 2.Click Edit to enter edit mode
3. 3.Make changes (the editor shows your modifications)
4. 4.Click Save when done
5. 5.Enter a change summary (this is important!)
6. 6.Confirm to create the new version

The Change Summary: Your Future Self's Best Friend#

When you save, Gameframe asks "What changed?" This isn't optional politeness—it's essential documentation.

Bad summaries:

• —"Updated"
• —"Changes"
• —"Fixed stuff"
• —"v2"

Good summaries:

• —"Buffed warrior health 100→150 based on Dec 1 playtest feedback"
• —"Removed shield mechanic per design review - too defensive"
• —"Added mage abilities: Fireball (50 dmg), Frost Nova (30 dmg + slow)"
• —"Reorganized abilities section for clarity - no content changes"

The test: In 3 months, will you understand what this change was about just from reading the summary? If yes, it's good.

Version Numbers and Meaning#

Versions are numbered sequentially: v1, v2, v3, etc.

Some teams add semantic meaning:

• —v1.x = Minor changes, balancing
• —v2.0 = Major revision, structural changes
• —v3.0 = Complete rewrite

Gameframe doesn't enforce this—use whatever convention works for your team.

§Part 3: The Diff Viewer (Where Magic Happens)#

What Is a Diff?#

A "diff" (short for difference) shows exactly what changed between two versions. Not "edited by Sarah"—the actual changes, line by line.

This is the killer feature. This is what Notion and Google Docs can't do.

Reading Diff Colors#

When you compare two versions, you'll see:

Visual Example#

Comparing v1 to v3 of a balance document:

## Player Stats

- player_health: 100
+ player_health: 150
  player_mana: 50
- shield_duration: 3 seconds
+ shield_duration: 5 seconds
- shield_cooldown: 10 seconds
+ rage_meter_max: 100
+ rage_decay_rate: 5 per second

Reading this:

• —Health increased from 100 to 150
• —Mana stayed at 50 (context line)
• —Shield duration increased from 3 to 5 seconds
• —Shield cooldown was REMOVED entirely
• —Rage meter system was ADDED (two new lines)

In 5 seconds, you understand exactly what changed. No digging. No asking around.

How to Compare Versions#

Method 1: From Document View

1. 1.Open your document
2. 2.Click History button
3. 3.You'll see the version timeline
4. 4.Select two versions (checkboxes)
5. 5.Click Compare

Method 2: Quick Compare

1. 1.Open your document
2. 2.Click Compare button
3. 3.Select "From" version (e.g., v1)
4. 4.Select "To" version (e.g., current)
5. 5.View the diff

Method 3: Compare Adjacent

1. 1.In History view
2. 2.Click the diff icon between any two adjacent versions
3. 3.See what changed in that specific save

Advanced: Three-Way Diffs#

When resolving merge conflicts (see Branching Guide), you'll see three-way diffs:

• —Base - The common ancestor
• —Theirs - Changes from one branch
• —Yours - Changes from another branch

This helps you understand whose changes to keep when there's a conflict.

§Part 4: Reverting to Previous Versions#

When You Need to Revert#

Common scenarios:

• —Playtest disaster: Balance change broke the game, need to undo
• —Design reversal: Stakeholder wants to go back to previous direction
• —Accidental deletion: Someone removed a section by mistake
• —Experiment failed: Tried a new structure, didn't work
• —Finding bugs: Implemented feature from wrong version

How to Revert#

1. 1.Open document History
2. 2.Find the version you want (read the summaries!)
3. 3.Click Revert to this version
4. 4.Confirm the action

What happens: A NEW version is created with the old content.

If you're at v5 and revert to v2, you'll have:

v6 - "Reverted to v2" (content matches v2)
v5 - Your last change
v4 - Previous change
v3 - Previous change
v2 - The version you reverted to
v1 - Original

Why Revert Creates a New Version#

This is important: reverting is non-destructive.

You can revert to v2, decide that was wrong, and revert to v4. Or revert to v6 (which was your revert). Everything is preserved.

This is different from "undo" in most apps. Undo loses history. Revert preserves it.

Partial Reverts (Manual)#

Sometimes you want to revert just ONE change, not everything. Here's how:

1. 1.Open the diff between the version with the change and the one before
2. 2.Note what was changed
3. 3.Edit the current document
4. 4.Manually undo just that part
5. 5.Save with a summary like "Reverted warrior health change (keeping other v3 changes)"

Gameframe doesn't have automatic partial reverts yet, but understanding the diff makes manual partial reverts easy.

§Part 5: Best Practices from Professional Teams#

Practice 1: Commit Early, Commit Often#

Bad pattern:

• —Edit for 3 hours
• —Make 15 different changes
• —Save once: "Updated balance doc"

Good pattern:

• —Change warrior stats → Save: "Buffed warrior health 100→150"
• —Change mage stats → Save: "Nerfed mage fireball damage 80→60"
• —Reorganize sections → Save: "Moved abilities before items for better flow"

Why: Small, focused saves are easier to understand, easier to revert, and easier to discuss.

Practice 2: Save Before and After Meetings#

Before a meeting:

Compare last week's version to current. Come prepared: "Here's what changed since last time."

After a meeting:

Save with context: "Applied design review feedback: reduced all cooldowns 20%"

Your version history becomes a record of decisions, not just changes.

Practice 3: Use History for Onboarding#

New team member or contractor? Tell them: "Read the version history of these three documents."

They'll see:

• —How the design evolved
• —Why decisions were made
• —What the current thinking is
• —Who to ask about specific areas

Way better than a static "onboarding doc" that's probably outdated.

Practice 4: Link Changes to External Context#

Reference external info in your summaries:

• —"Fixed per JIRA-1234"
• —"Applied changes from Dec 1 playtest (see Slack #playtesting)"
• —"Publisher feedback round 2 - see email thread"

Your version history becomes an audit trail.

Practice 5: Review Diffs in Code Review Style#

Before merging branches or accepting major changes:

1. 1.Open the diff
2. 2.Read through every change
3. 3.Ask: Does this make sense? Is anything missing?
4. 4.Approve or request changes

Treat important design docs like code—review before accepting.

§Part 6: Version Control vs. "Version History"#

The Competition: What Others Offer#

Notion:

• —Shows "edited by X on Y date"
• —Can restore old versions
• —Cannot see what actually changed
• —Cannot compare arbitrary versions
• —30-day history limit on free plans

Google Docs:

• —Shows timestamped versions
• —Can name versions (if you remember)
• —Cannot see diffs
• —Cannot compare arbitrary versions
• —Reverting overwrites current

Confluence:

• —Shows version list
• —Basic diff (limited)
• —Slow and clunky
• —Not designed for games

The Gameframe Difference#

§Part 7: Keyboard Shortcuts and Power User Tips#

Keyboard Shortcuts#

Power User Tips#

Tip 1: Use the search in history

Large documents have long histories. Use the search box to find versions by summary text.

Tip 2: Star important versions

Mark milestones (pre-release, post-playtest, approved-by-publisher) for easy finding.

Tip 3: Export history for reports

Need to show stakeholders what changed? Export version history as a changelog.

Tip 4: Set up notifications

Get alerts when specific documents are changed. Never be surprised by a "when did this change?" again.

§Part 8: Troubleshooting Common Issues#

"I can't find the version I need"#

• —Use search within history
• —Check if you're on the right branch
• —Look at timestamps, not just version numbers

"The diff is too large to read"#

• —Break your changes into smaller saves next time
• —Use the "collapse unchanged" option
• —Focus on specific sections

"I accidentally saved without a good summary"#

• —Edit the version metadata (if available)
• —Create a new version with a "Documentation: [actual summary]" note
• —Learn for next time—good summaries are a habit

"Someone else edited while I was editing"#

• —Gameframe warns you before this becomes a conflict
• —Save your work to a new branch
• —Merge when ready (see Branching Guide)

§Summary: The Version Control Mindset#

Version control in Gameframe means:

1. 1.Every change is permanent - Nothing is ever truly deleted
2. 2.Every change is explained - Change summaries create context
3. 3.Any two points are comparable - The diff viewer shows exactly what changed
4. 4.Reverting is safe - Creates new history, doesn't destroy old
5. 5.History is documentation - Your version log tells the story of your design

The Transformation#

Before version control:

• —"Which version is current?"
• —"When did this change?"
• —"Can we go back?"
• —Hours lost to confusion

After version control:

• —Current version is always clear
• —History shows every change
• —Going back takes one click
• —Confidence in your documentation

§Next Steps#

Now that you understand versions:

• —Branching Like a Pro: Learn to experiment safely with branches
• —Contractor Access Setup: Add teammates with proper permissions
• —Quest Log Mastery: Track tasks alongside your versioned docs

You'll never lose work again. You'll never wonder "what changed?" again. You'll never be afraid to experiment again.

That's the power of version control for game design.

Ready to start? Create your free account and experience true version control for your game design documents.