---
title: "Versioning"
description: "Track changes, manage baselines, and maintain audit trails for all artifacts"
---

# Versioning

TraceRTM provides comprehensive versioning capabilities to track changes to artifacts over time, manage baselines, support branching workflows, and maintain complete audit trails for compliance.

## Why Versioning Matters

### Change Tracking

Every modification to artifacts is recorded:

```python
from tracertm import TraceRTMClient

client = TraceRTMClient()

# Get item with version info
item = client.get_item("FEAT-001")

print(f"Current version: {item.version}")
print(f"Created: {item.created_at}")
print(f"Last modified: {item.updated_at}")
print(f"Modified by: {item.updated_by}")
```

### Audit Compliance

Versioning supports regulatory requirements:

- **FDA 21 CFR Part 11** - Electronic records and signatures
- **ISO 26262** - Automotive safety traceability
- **DO-178C** - Aviation software development
- **IEC 62304** - Medical device software

## Key Concepts

### Version Numbers

Each artifact has an auto-incrementing version number:

```python
# Create item (version 1)
item = client.create_item(
    title="Authentication Feature",
    item_type="feature"
)
print(f"Version: {item.version}")  # 1

# Update item (version 2)
client.update_item(item.id, description="OAuth2 authentication")
item = client.get_item(item.id)
print(f"Version: {item.version}")  # 2
```

### Change History

View the complete history of changes:

```python
# Get full history
history = client.get_history(item.id)

for change in history:
    print(f"v{change.version} - {change.timestamp}")
    print(f"  Changed by: {change.user}")
    print(f"  Fields: {', '.join(change.changed_fields)}")
```

```bash
# CLI history
tracertm history FEAT-001

# Output:
# History for FEAT-001
# ════════════════════════════════════════
# v3  2024-12-10 14:30  user@example.com
#     Changed: status (in_progress → done)
#
# v2  2024-12-05 09:15  user@example.com
#     Changed: description, metadata.story_points
#
# v1  2024-12-01 10:00  user@example.com
#     Created
```

### Baselines

Baselines capture a snapshot of artifacts at a point in time:

```python
# Create a baseline
baseline = client.create_baseline(
    name="v1.0-release",
    description="Release 1.0 baseline",
    items=["FEAT-001", "FEAT-002", "CODE-*", "TEST-*"]
)

# List baselines
baselines = client.list_baselines()
for b in baselines:
    print(f"{b.name}: {b.item_count} items, {b.created_at}")
```

```bash
# CLI baselines
tracertm baseline create "v1.0-release" --include "FEAT-*" --include "TEST-*"
tracertm baseline list
tracertm baseline show "v1.0-release"
```

## Versioning Features

### Compare Versions

```python
# Compare two versions
diff = client.compare_versions(
    item_id="FEAT-001",
    from_version=1,
    to_version=3
)

print(f"Changes from v1 to v3:")
for field, change in diff.items():
    print(f"  {field}: {change['old']} → {change['new']}")
```

```bash
# CLI compare
tracertm diff FEAT-001 --from 1 --to 3

# Output:
# FEAT-001: v1 → v3
# ════════════════════════════════════════
# title:
#   - Authentication
#   + User Authentication with OAuth2
#
# status:
#   - draft
#   + done
#
# metadata.story_points:
#   - 5
#   + 13
```

### Restore Previous Version

```python
# Restore to a previous version
client.restore_version(
    item_id="FEAT-001",
    version=2,
    reason="Reverting incorrect changes"
)
```

### Branch and Merge

For complex workflows, create branches:

```python
# Create a branch
branch = client.create_branch(
    name="feature/new-auth",
    from_baseline="main"
)

# Make changes in branch
client.update_item("FEAT-001", branch="feature/new-auth", ...)

# Merge branch
client.merge_branch(
    source="feature/new-auth",
    target="main",
    strategy="theirs"  # or "ours", "manual"
)
```

## Configuration

```yaml
# .tracertm/config.yaml
versioning:
  # Auto-increment versions
  auto_version: true

  # Retain history
  history:
    enabled: true
    retention_days: 365  # Keep 1 year of history

  # Baseline settings
  baselines:
    auto_baseline_on_status:
      - done
      - released

  # Branching
  branching:
    enabled: true
    default_branch: main
    protected_branches:
      - main
      - release/*
```

## Topics

Explore versioning capabilities in detail:

- [Versioning Strategies](/docs/wiki/concepts/versioning/strategies) - Approaches to version management
- [Branching](/docs/wiki/concepts/versioning/branching) - Working with branches
- [Merging](/docs/wiki/concepts/versioning/merging) - Combining changes
- [History](/docs/wiki/concepts/versioning/history) - Audit trails and change logs
- [Rollback](/docs/wiki/concepts/versioning/rollback) - Reverting changes

## Related Topics

- [Workflows](/docs/wiki/concepts/workflows) - Status transitions
- [Validation](/docs/wiki/concepts/metadata/validation) - Version validation
- [Reports](/docs/getting-started/first-project/reports) - Version reports

