ldpv2/doc/stories/STORY-5-Versions.md

Story 5: Version Management

Story Overview

As a application manager
I want to track application versions
So that I can manage releases and their lifecycle

Story Type: Feature (Core Domain)
Priority: High
Estimated Effort: 3-4 days
Dependencies: Story 2 (Applications)

---

Business Value

Versions represent application releases. This enables:

• Tracking what versions exist for each application
• Version lifecycle management (release date, end-of-life)
• Foundation for deployment tracking (Story 6)
• Link to external references (Git tags, JIRA releases)

---

Scope

In Scope

✅ Version CRUD operations
✅ Version-Application association
✅ Version lifecycle (release date, end-of-life)
✅ External reference tracking (Git, JIRA, etc.)
✅ Version listing per application

Out of Scope

❌ Deployment tracking (Story 6)
❌ Version comparison/diff
❌ Automated version detection from CI/CD

---

Database Schema

CREATE TABLE version (
    id UUID PRIMARY KEY,
    application_id UUID NOT NULL REFERENCES application(id) ON DELETE CASCADE,
    version_identifier VARCHAR(100) NOT NULL, -- "1.2.3", "2024.Q1"
    external_reference VARCHAR(500), -- Git tag, JIRA link, etc.
    release_date DATE NOT NULL,
    end_of_life_date DATE,
    created_at TIMESTAMP NOT NULL,
    updated_at TIMESTAMP NOT NULL,
    UNIQUE(application_id, version_identifier)
);

CREATE INDEX idx_version_application ON version(application_id);
CREATE INDEX idx_version_release_date ON version(release_date);

---

Key Endpoints

• GET /api/applications/{appId}/versions - List versions for application
• GET /api/versions/{id} - Get version details
• POST /api/applications/{appId}/versions - Create version
• PUT /api/versions/{id} - Update version
• DELETE /api/versions/{id} - Delete version
• GET /api/versions/latest?applicationId={appId} - Get latest version

---

DTOs

export interface Version {
  id: string;
  applicationId: string;
  versionIdentifier: string; // "1.2.3"
  externalReference?: string; // "https://github.com/org/repo/releases/tag/v1.2.3"
  releaseDate: Date;
  endOfLifeDate?: Date;
  createdAt: Date;
  updatedAt: Date;
}

export interface CreateVersionRequest {
  versionIdentifier: string;
  externalReference?: string;
  releaseDate: Date;
  endOfLifeDate?: Date;
}

---

Frontend Components

VersionListComponent (sub-component of ApplicationDetailComponent)

• Displayed as tab in Application Detail view
• Table: Version, Release Date, End of Life, External Reference, Actions
• "Add New Version" button
• Sort by release date (newest first)
• Actions: Edit, Delete

VersionFormComponent

• Modal or inline form
• Fields:
  • Version Identifier (required, must be unique per application)
  • External Reference (optional, URL)
  • Release Date (required, date picker)
  • End of Life Date (optional, must be after release date)
• Validation:
  • Version identifier unique within application
  • Dates valid (EOL after release)

---

Business Rules

1. Unique Version: Version identifier must be unique within an application
2. Date Logic: End-of-life date (if set) must be after release date
3. Latest Version: System tracks the version with the most recent release date as "latest"
4. Deletion: Can only delete version if not deployed anywhere (checked in Story 6)

---

Acceptance Criteria

• Version can be created for an application
• Version identifier must be unique within application
• Duplicate version identifiers are rejected
• Version release date is required
• End-of-life date validation (must be after release)
• Versions listed per application
• Versions sorted by release date (newest first)
• Latest version is identifiable
• Version can be edited
• Version can be deleted
• External reference links are clickable
• Tests pass (>80% backend, >70% frontend)

---

Testing Scenarios

1. Create Version: Add version "1.0.0" to an application
2. Duplicate Version: Attempt to create "1.0.0" again (should fail)
3. Multiple Versions: Create versions 1.0.0, 1.1.0, 2.0.0, verify sorting
4. Latest Version: Verify version with most recent release date marked as latest
5. Edit Version: Update end-of-life date
6. Delete Version: Delete version (if not deployed)
7. Date Validation: Set EOL before release date (should fail)

---

Integration with Application Detail

The Application Detail page (from Story 2) will be enhanced with a "Versions" tab:

Application Detail
├── Overview (existing)
├── Versions (NEW)
│   ├── Version List
│   └── Add Version Button
├── Deployments (Story 6)
└── Contacts (Story 3)

---

Story Status: Ready for Development
Estimated Completion: 3-4 days