EuConquisto Composer MCP

# Versioning Enforcement Guide **Document Version**: 1.0 **Project Version**: 0.1.0 **Last Updated**: 2025-06-08 **Status**: Active ## 🎯 Purpose This guide ensures consistent versioning practices throughout the EuConquisto Composer MCP Server PoC development lifecycle. Every team member must follow these protocols to maintain project integrity and release management. ## 📋 Versioning Protocol Overview ### Core Principles 1. **Every file has version information** 2. **Every change is tracked and documented** 3. **Compatibility is always validated** 4. **Automation enforces consistency** 5. **Documentation reflects current state** ### Version Scheme - **Project Versioning**: Semantic Versioning (semver.org) - Format: `MAJOR.MINOR.PATCH` - Current: `0.1.0` (Foundation Release) - **Document Versioning**: Independent versioning per document - **File Versioning**: Header-based version tracking ## 🔄 4-Phase Versioning Requirements ### Phase 1: Planning & Design **MANDATORY TASKS:** - [ ] Update `project.json` with task planning status - [ ] Plan version increments (if applicable) - [ ] Document compatibility requirements - [ ] Update `docs/project-management/ROADMAP.md` task status - [ ] Identify versioning impact level **Versioning Impact Assessment:** - **Major (x.0.0)**: Breaking changes, API incompatibility - **Minor (0.x.0)**: New features, backward compatible - **Patch (0.0.x)**: Bug fixes, documentation updates ### Phase 2: Implementation **MANDATORY TASKS:** - [ ] Add version headers to all new files - [ ] Update `package.json` version (if needed) - [ ] Maintain compatibility matrix - [ ] Update `project.json` metadata - [ ] Validate dependencies compatibility **File Header Template:** ```typescript /** * EuConquisto Composer MCP Server - [Component Name] * * @version [Project Version] * @created [Creation Date] * @updated [Last Update Date] * @author [Author Name] * * @description [Component description and purpose] * * @testStatus PENDING | PASSING | FAILING * @coverage [percentage]% * * @dependencies * - [dependency list] * * @supersedes [file path if applicable] * @supersededBy [file path if applicable] */ ``` ### Phase 3: Documentation **MANDATORY TASKS:** - [ ] Update `CHANGELOG.md` with task completion - [ ] Version all new documentation - [ ] Update `README.md` status information - [ ] Refresh `VERSION` file if needed - [ ] Update API documentation versions **Documentation Version Pattern:** ```markdown **Document Version**: [Document Version] **Project Version**: [Project Version] **Last Updated**: [Date] ``` ### Phase 4: Verification **MANDATORY TASKS:** - [ ] Validate all version information is current - [ ] Update project completion percentage - [ ] Document version in validation reports - [ ] Prepare next task versioning requirements - [ ] Run automated version consistency checks ## 🛠 Automation & Tools ### Version Consistency Checks Add to `tools/run-quality-checks.sh`: ```bash # Version Consistency Validation check_version_consistency() { print_status "Checking version consistency..." PROJECT_VERSION=$(grep '"version"' package.json | cut -d'"' -f4) VERSION_FILE_VERSION=$(grep "Version.*:" VERSION | head -1 | cut -d':' -f2 | xargs) README_VERSION=$(grep "Version.*:" README.md | head -1 | cut -d':' -f2 | xargs) if [ "$PROJECT_VERSION" = "$VERSION_FILE_VERSION" ] && [ "$PROJECT_VERSION" = "$README_VERSION" ]; then print_success "Version consistency validated" else print_error "Version inconsistency detected" return 1 fi } ``` ### Project Metadata Updates Update `project.json` with each task: ```bash # Update project completion update_project_progress() { local completed_tasks=$1 local total_tasks=15 local percentage=$((completed_tasks * 100 / total_tasks)) # Update project.json with new progress jq ".development.completedTasks = $completed_tasks | .development.progressPercentage = $percentage" project.json > temp.json mv temp.json project.json } ``` ## 📝 File-Specific Requirements ### TypeScript Files (.ts) - **Required**: Full TSDoc header with version - **Required**: @version, @created, @updated tags - **Required**: Dependency documentation - **Optional**: @supersedes/@supersededBy for refactoring ### Documentation Files (.md) - **Required**: Version metadata section - **Required**: Document version tracking - **Required**: Last updated date - **Optional**: Change summary for major updates ### Configuration Files (.json, .js) - **Required**: Version comment header - **Required**: Compatibility information - **Optional**: Change notes in comments ### Scripts (.sh, .ts) - **Required**: Version header in comments - **Required**: Dependencies list - **Required**: Last updated information ## 🔍 Quality Gates ### Pre-Commit Validation ```bash #!/bin/bash # Pre-commit hook for version validation # Check all TypeScript files have version headers check_ts_headers() { for file in $(git diff --cached --name-only --diff-filter=A | grep '\.ts$'); do if ! grep -q "@version" "$file"; then echo "Error: $file missing version header" exit 1 fi done } # Check documentation has version info check_doc_versions() { for file in $(git diff --cached --name-only --diff-filter=A | grep '\.md$'); do if ! grep -q "Document Version" "$file"; then echo "Warning: $file missing document version" fi done } check_ts_headers check_doc_versions ``` ### Release Validation Before any version increment: 1. All files must have current version headers 2. CHANGELOG.md must be updated 3. VERSION file must reflect new version 4. project.json must be synchronized 5. README.md status must be current ## 📊 Version Tracking Matrix | Component | Current Version | Last Updated | Next Version | |-----------|----------------|--------------|--------------| | Project | 0.1.0 | 2025-06-08 | 0.2.0 | | README.md | 1.0 | 2025-06-08 | TBD | | ROADMAP.md | 1.0 | 2025-06-08 | TBD | | CHANGELOG.md | 1.0 | 2025-06-08 | TBD | | package.json | 0.1.0 | 2025-06-08 | TBD | ## 🚨 Common Violations & Penalties ### Critical Violations (Block Merge) - Missing version headers on new files - Inconsistent version numbers across files - Undocumented breaking changes - Missing CHANGELOG entries ### Warning Violations (Review Required) - Outdated documentation versions - Missing dependency updates - Incomplete file headers - Uncommitted version changes ## 🔄 Task-Specific Checklists ### For Every Task Phase 1 ``` 📋 Versioning Requirements Assessment: - [ ] Determine version impact (major/minor/patch) - [ ] Document compatibility requirements - [ ] Plan documentation updates needed - [ ] Identify affected file headers - [ ] Update project.json task status - [ ] Update ROADMAP.md phase completion ``` ### For Every Task Phase 2 ``` 📋 Implementation Versioning: - [ ] Add version headers to all new files - [ ] Update modified file headers - [ ] Validate dependency compatibility - [ ] Update package.json if needed - [ ] Maintain project.json metadata ``` ### For Every Task Phase 3 ``` 📋 Documentation Versioning: - [ ] Update CHANGELOG.md with changes - [ ] Version new documentation files - [ ] Update README.md status - [ ] Refresh VERSION file if needed - [ ] Update API documentation ``` ### For Every Task Phase 4 ``` 📋 Verification Versioning: - [ ] Run version consistency checks - [ ] Validate all version information - [ ] Update completion percentage - [ ] Document version in reports - [ ] Prepare next task requirements ``` ## 🎯 Success Metrics ### Compliance Tracking - **100%** of files have version headers - **100%** version consistency across project - **0** undocumented changes - **Automated** validation passing ### Quality Indicators - Version increments follow semantic versioning - Documentation versions tracked independently - Compatibility matrix maintained - Change history complete ## 📞 Support & Questions For versioning questions or clarifications: 1. Review this guide first 2. Check existing examples in codebase 3. Consult docs/project-management/ROADMAP.md task requirements 4. Validate with quality tools --- ## 📜 Document Information **Document Version**: 1.0 **Project Version**: 0.1.0 **Format**: Enforcement Guide **Scope**: All development activities **Compliance**: Mandatory **Review Cycle**: Updated with major process changes **Last Review**: 2025-06-08 **Next Review**: Upon process improvements --- *This guide is the authoritative source for versioning requirements and must be followed by all team members.* *EuConquisto Composer MCP Server PoC - Versioning Enforcement Guide v1.0* *Project Version 0.1.0 | Foundation Release | © 2025 EuConquisto Development Team*