VERSION-STRATEGY.mdā¢3.87 kB
---
document: Version Control Strategy
version: 1.0.0
status: active
author: Claude
created: 2024-06-01
last_updated: 2024-06-01
---
# Version Control Strategy
## šÆ Overview
This project uses semantic versioning and Git-based version control with strict naming conventions.
## š Semantic Versioning
Format: `MAJOR.MINOR.PATCH`
- **MAJOR**: Breaking changes
- **MINOR**: New features (backward compatible)
- **PATCH**: Bug fixes and minor updates
Examples:
- `1.0.0` - First stable release
- `1.1.0` - Added new feature
- `1.1.1` - Fixed bug in 1.1.0
## š§ File Versioning
### For Configuration Files
```
# Use git tags, single file
docker-compose.yml # Tagged as v1.0.0, v1.1.0, etc.
# Or explicit versions when needed
workflow-v1.0.0.json
workflow-v2.0.0.json
```
### For Documentation
```
# Single file with git history
architecture.md # Use git to track changes
# Or versioned when parallel versions needed
api-spec-v1.md
api-spec-v2.md
```
### NEVER Use
- `enhanced_config.yml`
- `improved_workflow.json`
- `new_architecture.md`
- `better_solution.js`
- `final_FINAL_v2.json`
## šæ Git Branching Strategy
### Branch Types
```
main # Production-ready code
āāā develop # Integration branch
āāā component-a/* # Infrastructure tasks
āāā component-b/* # Workflow tasks
āāā component-c/* # UI tasks
āāā component-d/* # Demo tasks
```
### Branch Naming
```
component-{letter}/task-{number}-{description}
Examples:
component-a/task-001-project-init
component-b/task-008-workflow-import
component-c/task-015-api-development
```
## š Commit Message Format
```
<type>(<scope>): <subject> [TASK-XXX]
<body>
<footer>
```
### Types
- `feat`: New feature
- `fix`: Bug fix
- `docs`: Documentation changes
- `style`: Code style changes
- `refactor`: Code refactoring
- `test`: Test additions/changes
- `chore`: Maintenance tasks
### Examples
```bash
feat(infra): add docker compose configuration [TASK-002]
fix(workflow): correct gemini api endpoint [TASK-009]
docs(api): add endpoint documentation [TASK-015]
```
## š·ļø Git Tags
### Component Milestones
```bash
# After completing each component
git tag -a component-a-complete -m "Infrastructure setup complete"
git tag -a component-b-complete -m "Workflows implemented"
```
### Version Releases
```bash
# For major milestones
git tag -a v0.1.0 -m "Infrastructure ready"
git tag -a v0.2.0 -m "Core workflows functional"
git tag -a v0.3.0 -m "UI implemented"
git tag -a v1.0.0 -m "PoC complete"
```
## š Version Tracking
### In Code Files
```javascript
/**
* @version 1.0.0
* @since 2024-06-01
* @author DocProc Team
*/
```
### In Configuration
```yaml
# docker-compose.yml
# Version: 1.0.0
# Last Updated: 2024-06-01
```
### In Documentation
```markdown
---
version: 1.0.0
last_updated: 2024-06-01
---
```
## š Version Migration
When updating versions:
1. **Document the change**
```markdown
## Migration from v1.x to v2.x
- Breaking change: [description]
- Migration steps: [list]
```
2. **Update CHANGELOG.md**
```markdown
## [2.0.0] - 2024-06-01
### Breaking Changes
- Changed API endpoint structure
```
3. **Tag the release**
```bash
git tag -a v2.0.0 -m "Major version update"
```
## š Version Archive
Deprecated versions are moved to:
```
.meta/versions/
āāā v1.0.0/
ā āāā README.md
ā āāā deprecated-files/
āāā v2.0.0/
āāā migration-guide.md
```
## ā
Version Checklist
Before creating a new version:
- [ ] All tests pass
- [ ] Documentation updated
- [ ] CHANGELOG.md entry added
- [ ] Migration guide written (if needed)
- [ ] Previous version archived
- [ ] Git tag created
- [ ] Team notified
---
*This strategy ensures clear version tracking and smooth transitions between versions.*