Versioning & Change Tracking

Track changes, compare versions, and maintain baselines

Gear List Versioning provides per-project change tracking. Every time you export a PDF, the current state is captured as a baseline. From that point, all additions, modifications, and removals are tracked and highlighted — so you always know what changed since the last export.

Requirements

Functional Requirements

ID	Requirement	Acceptance Criteria	Priority	Source
REQ-VER-001	The system shall capture a baseline snapshot of the gear list on every successful PDF export	Export PDF → baseline saved with timestamp; subsequent edits show diff vs baseline; failed export → no baseline update	Must	`projects`
REQ-VER-002	The system shall track and visually highlight Added (green), Modified (yellow), and Removed (red) items relative to the last baseline	Delete → item removed from view and storage; undo available if applicable; confirm dialog shown	Must	`projects`
REQ-VER-003	The system shall compare device name, quantity, notes, status, category assignment, and custom attributes	View diff → added items green, removed red, changed yellow; each field compared; unchanged fields hidden	Must	`computeDiff`
REQ-VER-004	The system shall support manual baseline creation via "Set Baseline" action	Click "Set Baseline" → current state saved as baseline; diff shows changes since baseline; timestamp recorded	Must	`useVersionEditor` + `useVersioning`
REQ-VER-005	The system shall maintain a version history with the ability to view, switch, and compare versions	Open history → list of versions with timestamps; click version → loads that state; compare → side-by-side diff	Must	`versionHistoryService` + `useVersionEditor`
REQ-VER-006	The system shall support auto-increment and manual version number management	Save → version auto-increments; click version number → manual edit; format validated (semver); persists	Should	`versioning`
REQ-VER-007	The system shall preserve all versions — switching versions never discards data	Switch to v1 → data shows v1 state; switch to v3 → data shows v3; no data loss; original edits preserved	Must	`versionHistoryService`
REQ-VER-008	The system shall ignore corrupted baselines gracefully during migration	Trigger error → user-friendly message shown; no crash; recovery path available	Must	`projects`

Non-Functional Requirements

ID	Requirement	Metric	Priority
NFR-VER-001	Diff computation shall complete within 500ms for projects with ≤500 items	Diff perf	Should

Data Requirements

Baseline: Snapshot of entire gear list stored as JSON alongside the project
Version history: Array of versioned snapshots stored in IndexedDB
Diff engine: Compares fields in-memory; no separate diff storage
Persistence: Stored on the project object in IndexedDB → cloud sync

Constraints & Limits

Available to all tiers (Free and Pro)
Item order changes are not tracked — only content changes
Failed or cancelled exports do not update the baseline

Offline Behavior

Fully available offline — baselines, diffing, and version history are client-side
Version history syncs to cloud when connectivity is restored

Dependencies

Requires: Projects — versioning tracks project changes
Required by: Collaboration — diff view for conflict resolution

How It Works

Add items → Edit gear list → Export PDF → Baseline saved → Continue editing → See changes highlighted

You work on a gear list — adding, editing, and removing items as usual
You export a PDF — the current state is saved as a baseline snapshot
You continue editing — changes since the last export are automatically tracked
Visual diff indicators show you exactly what changed

Visual Change Indicators

When you have a baseline, the gear list highlights changes:

Indicator	Meaning	Visual Style
🟢 Added	Item exists now but not in the baseline	Green highlight
🟡 Modified	Item exists in both but fields differ	Yellow highlight
🔴 Removed	Item was in baseline but no longer present	Red strikethrough
⚪ Unchanged	Item is identical to baseline	No highlight

What Fields Are Tracked

The diff engine compares:

Device name and quantity
Notes and status fields
Category assignment (moved items are tracked)
Custom attributes

Item order changes are not tracked — only content changes matter.

Managing Versions

Version Number

Each project has a version number that increments automatically or manually:

Auto-increment: Version bumps on each PDF export (if enabled in settings)
Manual control: Set version numbers explicitly for your own tracking

Version History

Projects maintain a history of versions. You can:

View history: Open the version history panel to see past snapshots
Switch versions: Restore a previous version's gear list
Compare: See side-by-side differences between any two versions

Switching Versions

When you switch to a previous version:

The current state is preserved in history
The selected version becomes the active gear list
No data is lost — all versions remain accessible

Baselines

Automatic Baselines

Baselines are created automatically after a successful PDF export:

The PDF is generated and downloaded
The current snapshot is saved as the new baseline
The version number increments (if auto-increment is on)
All change indicators reset

Manual Baselines

You can also set a baseline manually:

Open the project workspace
Click ⋮ (More) → Set Baseline
The current state becomes the reference point for future change tracking

Baseline Rules

Baselines are only updated after successful exports — failed or cancelled exports don't affect the baseline
If a baseline is corrupted during migration, it is safely ignored
Manual version edits don't touch the baseline unless explicitly chosen

Offline-First

All versioning data is stored locally alongside the project in IndexedDB. No cloud connection is required for change tracking to work.

When Cloud Sync is enabled, version history syncs across devices.

Tips

Export regularly: Each export creates a fresh baseline, giving you a clean diff starting point
Review changes before export: Check the highlighted items to ensure you haven't missed anything
Use version history for rollback: If you made unwanted changes, switch to a previous version
Manual baselines for reviews: Set a baseline before sending a gear list for review, then track changes made during the review process

Last Updated: 2026-09-08 Version: 0.790.2

Versioning & Diff