Versioning

Catalio uses several distinct versioning patterns, each designed for a different kind of change. Understanding which pattern applies — and why — helps you build a reliable, traceable record of how your systems and specifications evolve over time.

The three patterns are:

1. Application Versions — explicit snapshots of a software system state, used as anchors for journey capture and before/after comparison
2. Automatic change history — field-level audit tracking on many Catalio resources, recording who changed what and when
3. Superseding — a semantic replacement pattern specific to Requirements, where an old requirement is formally replaced by a new one while both remain in the system

Application Versions

An Application Version is a named, discrete snapshot of an Application at a point in time. It might represent a specific software release, a particular environment state (production vs. staging), or a design milestone before a modernization effort.

Why Versions Exist

Journeys in Catalio are anchored to a specific Application Version. Without this anchor, journey data is ambiguous — a journey captured against a legacy system in January and a journey captured against the same system after a major patch in June may describe meaningfully different user experiences. Application Versions make that distinction explicit and queryable.

This anchoring enables the core Catalio modernization workflow:

1. Define a legacy Application Version (e.g., "Oracle EBS 12.2.9 Pre-Migration")
2. Capture journeys against that version — recording friction, step sequences, and pain points
3. Define a target Application Version (e.g., "Target SaaS Platform v1")
4. Capture journeys against the new system once available
5. Create a Journey Comparison to prove measurable UX improvement

Key Fields

Each application can have only one version with a given label — duplicate labels under the same parent are not allowed.

Relationship to Application and Journeys

Application Versions are always children of a parent Application. An orphaned version cannot exist. Each version collects the Journeys recorded against that version of the system.

Common Patterns

Legacy modernization — create a “Legacy” version as the baseline, then a “Target” version as a placeholder before the new system exists. Pre-wire your journey captures and comparison structures early.

Incremental release tracking — create one version per meaningful release boundary (v2.0, v3.0), not one per patch. Versions should correspond to states where user experience measurably differs.

Environment-based analysis — create separate versions for “Production” and “UAT” when you need to compare how users behave in each environment.

Retirement — when a version is no longer active, mark it deprecated or archived rather than deleting it. Historical journey data remains intact and queryable.

Automatic Change History

Many resources in Catalio automatically record a change history for every create, update, and delete operation. This is field-level audit tracking — when a field value changes, the old and new values are captured in a history entry.

What Gets Recorded

Each history entry typically includes:

• The type of change (created, updated, or removed)
• The before and after values for each changed field
• A timestamp
• The user who made the change

Application Versions, Journey Comparisons, and many resources across journeys and documentation participate in this history system.

What You Can Do With It

The change history answers questions like:

• Who changed this Application Version’s status from active to deprecated, and when?
• What was the original metrics value on a Journey Comparison before it was updated?
• Has this resource been modified since it was created?

In Catalio’s UI, change history surfaces in activity feeds and audit views for supported resources.

What It Does Not Cover

Change history tracks field values on a resource — it does not always track relationship adds or removes (joining a Persona to a Requirement, for example) unless that relationship is tracked separately. For semantic replacement of a concept (an old requirement replaced by a new one), the superseding pattern is more appropriate.

The Superseding Pattern

The superseding pattern is specific to Requirements. It handles the case where a requirement’s meaning changes so significantly that the original can no longer be edited in place — a new requirement should be written instead, and the old one should be formally retired with a record of why.

How It Works

When a requirement needs to be replaced:

1. Create a new requirement containing the updated specification
2. Supersede the old requirement, linking it to the new one
3. Provide a reason explaining why the replacement was necessary
4. Add notes with further context if needed

Both requirements remain in the system. The old requirement is marked Superseded and points to the requirement that replaced it. The new requirement points back to what it superseded.

Example

REQ-001: "As a User, I want to export data as CSV so that I can analyze it in Excel"
  Status: Superseded → REQ-042
  Reason: "User feedback showed need for multiple formats and field selection"

REQ-042: "As a User, I want to export as CSV, JSON, or Excel with custom field selection
         so that I can analyze in multiple tools and choose relevant fields"
  Status: Active
  Supersedes: REQ-001

Why Not Just Edit?

Editing a requirement in place erases the history of what was originally specified. For audit-sensitive organizations (compliance, regulated industries), that history matters. The superseding pattern also makes impact visible — any test cases, use cases, or policies linked to REQ-001 remain attached to it, giving teams an explicit list of downstream artifacts that may need to be re-evaluated against the new specification.

When to Use Which Pattern

The patterns are not mutually exclusive. A requirement could be superseded (semantic replacement), and both the old and new requirement records retain their own change histories. The Application Version that journeys were captured against is also tracked, so you can see when its status or notes changed.

Best Practices

Name Application Versions for stakeholders, not machines. "Oracle 12.2.9 Pre-Migration" is clearer to a business analyst in a comparison report than "v12.2.9.0-legacy".

Create target versions before the system exists. You can create a "Target Design v1" Application Version as a placeholder before the modernized system is available. This lets you pre-wire journey capture sessions and comparison structures.

Let change history run silently. You do not need to think about audit tracking during normal usage — it captures changes automatically. Reference it when you need to investigate a change or produce an audit report.

Supersede rather than delete. When a requirement changes significantly, avoid deleting the original. The superseding relationship preserves the decision trail and keeps downstream artifacts (test cases, policies, components) connected to the historical record.

Retire old Application Versions explicitly. Mark versions deprecated when no longer active. This keeps the version picker clean without losing the journey history captured against them.

Next Steps

• Application — Understand the parent entity that Application Versions belong to
• Requirements — Learn more about the superseding lifecycle and requirement states
• Journey Comparisons — See how Application Versions enable rigorous before/after comparison
• Journeys — Understand how journeys are anchored to specific versions

Support

• Documentation: Continue reading about Applications and Journeys
• Email: support@catalio.ai
• Community: Share versioning strategies with other Catalio users