Skip to content

VERSION_CONTROL_README.md

Latest commit

 

History

History
254 lines (205 loc) · 7.62 KB

VERSION_CONTROL_README.md

File metadata and controls

254 lines (205 loc) · 7.62 KB
Raw

Course Content Version Control Implementation

Overview

This implementation provides comprehensive version control functionality for course content in the StarkEd Education platform. It allows course creators to track changes, maintain content history, compare versions, and rollback to previous versions when needed.

Features Implemented

✅ Automatic Version Creation

  • Versions are automatically created when content is updated
  • Configurable auto-versioning settings per content
  • Change tracking with descriptive change logs

✅ Version Management API Endpoints

  • Create new versions
  • List version history with pagination and filtering
  • Get current or specific versions
  • Update version metadata
  • Delete versions (with safety checks)

✅ Version Comparison Functionality

  • Deep comparison between any two versions
  • Visual diff showing additions, modifications, and removals
  • Summary statistics of changes
  • Cached comparisons for performance

✅ Rollback Capability

  • Restore any previous version with a single API call
  • Restore history tracking for audit purposes
  • Permission-based rollback controls
  • Restore reason logging

File Structure

backend/
├── src/
│   ├── models/
│   │   ├── Content.ts                    # Enhanced with version tracking
│   │   └── ContentVersion.ts             # Version control model and utilities
│   ├── routes/
│   │   └── courses.js                    # Version management endpoints
│   ├── middleware/
│   │   └── validation.ts                 # Content version validation
│   └── utils/
│       └── versionControl.ts             # Version control service
├── migrations/
│   └── 001_add_content_versions.js       # Database migration
├── tests/
│   └── versionControl.test.js            # Test suite
└── verify-implementation.js             # Implementation verification

API Endpoints

Version Management

  • POST /api/courses/:contentId/versions - Create new version
  • GET /api/courses/:contentId/versions - List version history
  • GET /api/courses/:contentId/versions/current - Get current version
  • GET /api/courses/:contentId/versions/:versionId - Get specific version
  • PUT /api/courses/:contentId/versions/:versionId - Update version
  • DELETE /api/courses/:contentId/versions/:versionId - Delete version

Version Operations

  • POST /api/courses/:contentId/versions/:versionId/restore - Restore version
  • GET /api/courses/:contentId/versions/:versionId/compare/:versionId2 - Compare versions
  • GET /api/courses/:contentId/versions/export - Export version history

Database Schema

content_versions

Stores all content versions with complete history:

  • id - Unique version identifier
  • content_id - Reference to parent content
  • version - Version number
  • title, description - Version metadata
  • content - Full content snapshot (JSON)
  • media_files - Associated media files
  • changes - Array of change descriptions
  • created_by - User who created the version
  • is_current - Whether this is the current version
  • created_at, published_at - Timestamps

version_comparison_cache

Caches version comparisons for performance:

  • content_id, version1, version2 - Comparison keys
  • comparison_data - Cached diff result
  • expires_at - Cache expiration

version_restore_history

Tracks all restore operations:

  • content_id - Reference to content
  • restored_from_version_id - Source version
  • restored_by - User who performed restore
  • restore_reason - Reason for restoration
  • restored_at - Restore timestamp

Usage Examples

Creating a New Version

POST /api/courses/content_123/versions
{
  "title": "Updated Lesson Content",
  "description": "Updated with new examples",
  "content": { "sections": [...] },
  "changes": ["Updated introduction", "Added new examples"],
  "createdBy": "instructor_456"
}

Getting Version History

GET /api/courses/content_123/versions?page=1&limit=10&sortBy=version&sortOrder=desc

Comparing Versions

GET /api/courses/content_123/versions/ver_1/compare/ver_2

Restoring a Version

POST /api/courses/content_123/versions/ver_1/restore
{
  "restoreReason": "Reverting to previous stable version",
  "restoredBy": "instructor_456"
}

Validation Rules

Content Version Creation

  • Content ID: Required, string
  • Title: Required, 3-200 characters
  • Description: Required, 10-1000 characters
  • Content: Required, valid JSON object
  • Changes: Required, non-empty array
  • Created By: Required, valid user ID

Version Operations

  • Version numbers must be positive integers
  • Cannot delete current version without replacement
  • Restore operations require appropriate permissions
  • Version comparisons limited to 100 versions for performance

Performance Optimizations

Caching

  • Version comparison results cached for 24 hours
  • Current version queries optimized with indexes
  • Media file comparisons use efficient hashing

Database Indexes

  • Composite indexes on content_id + version
  • Indexes on current version flags
  • Timestamp indexes for date-range queries
  • User-based indexes for permission checks

Pagination

  • Version history supports pagination (default: 10 per page)
  • Maximum 100 versions per page to prevent memory issues
  • Cursor-based pagination for large datasets

Security Considerations

Permission Controls

  • Version creation requires content edit permissions
  • Version deletion requires content owner or admin rights
  • Restore operations logged and audited
  • Version history cannot be modified (append-only)

Data Integrity

  • All versions stored as immutable snapshots
  • Cascade deletes handled safely
  • Foreign key constraints maintain consistency
  • Transaction-based operations for atomicity

Testing

The implementation includes comprehensive test coverage:

  • Unit tests for version control utilities
  • Integration tests for API endpoints
  • Validation rule testing
  • Performance benchmarking
  • Error handling verification

Run tests with:

npm test

Migration

To set up the database schema:

knex migrate:latest

To rollback if needed:

knex migrate:rollback

Configuration

Version control settings can be configured per content:

  • auto_versioning: Enable/disable automatic versioning
  • max_versions: Maximum versions to retain (default: 50)
  • cleanup_old_versions: Automatically cleanup old versions
  • retention_days: How long to keep old versions (default: 365)

Monitoring and Analytics

Version Metrics

  • Version creation frequency
  • Restore operation statistics
  • Comparison cache hit rates
  • Storage usage tracking

Audit Trail

  • Complete version history with timestamps
  • User attribution for all operations
  • Change descriptions for accountability
  • Restore operation logging

Future Enhancements

Planned Features

  • Branching and merging support
  • Collaborative editing with conflict resolution
  • Advanced diff visualization
  • Version tagging and release management
  • Automated version cleanup policies

Performance Improvements

  • Incremental version storage (diff-based)
  • Background comparison processing
  • Distributed caching for large deployments
  • Optimized media file versioning

Support

For issues or questions regarding the version control implementation:

  1. Check the test suite for usage examples
  2. Review the API documentation
  3. Consult the database schema documentation
  4. Contact the development team for assistance

Implementation Status: ✅ Complete
Acceptance Criteria: ✅ All met
Ready for Production: ✅ Yes