Content versioning

Why versioning matters

Think of a medical form or questionnaire you use to collect patient information. What happens if you suddenly change that form? People using older versions might record data differently than those using newer versions, making it difficult to compare results across patients.

Content versioning solves this problem. When we create healthcare data collection templates in Atticus, we carefully track each version to ensure:

1. Data Consistency: Healthcare professionals know exactly which version of a form they're using
2. Reliable Analysis: Data analysts can trust that information collected from the same version follows the same rules
3. Predictable Changes: When templates need updates, everyone understands how these changes might affect existing data

Once a template is marked as "Active" (approved for clinical use), we never change its content directly. Instead, we create a new version with a specific number that signals how compatible it is with previous versions. This approach ensures that data collected today can still be accurately analyzed alongside data collected last year.

Publication status: the life cycle of templates

Every template in our system has a status label that shows where it is in its lifecycle:

1. draft
   Description: An initial, unpublished version of the template that is not yet published or in use.
   Usage: Serves as the editable starting point for creating or updating a template.
   Transition: Can be published as either test or active, or continue to be edited.
   Note: Only one draft version can exist at a time. A draft can be deleted.

2. test
   

   Description: A versioned template published for testing purposes only.
   Usage: Used to validate and test the template before publishing it officially as active.
   Transition: Can later be published as active. Only the status changes, the version number will remain unchanged.
   Note: Only one test version can exist. Publishing a new test version will automatically retire the previous one.

3. active
   Description: A versioned template published for general use.
   Usage: Serves as the live, production version.
   Transition: Can be retired when it is no longer needed.
   Note: Only one active version can exist. Publishing a new active version will automatically retire the previous one.

4. retired
   Description: A version of the template that was previously active or test, but is no longer in use.
   Usage: Preserved for historical reference or record-keeping. Not used in active processes.
   Transition: A version becomes retired when:

   • A new version is published as active or test
   • The user manually retires it.

   Note: Multiple retired versions can exist to maintain version history.

When a template moves from draft to active, it becomes locked to preserve data integrity. This ensures that all data collected with that template version follows exactly the same structure.

How our versioning works

We use a simple numbering system (called semantic versioning) for all our templates. Each template has a version number with three parts, like this: 1.2.3

These numbers help everyone understand whether data collected with different versions will work together.

Version number explained

Each version number has three parts: MAJOR.MINOR.PATCH (like 1.2.3)

• First number (MAJOR): Signals big changes that affect data compatibility
• Middle number (MINOR): Indicates additions that don't break existing data
• Last number (PATCH): Shows small fixes that don't affect data at all

What each type of change means

1. Major changes (Example: 1.0.0 → 2.0.0)

   These are significant changes that mean old and new data won't work well together:

   • Removing questions from a form
   • Changing how a question is identified in the system
   • Changing what type of answer is expected (e.g., from text to numbers)
   • Adding stricter rules about what answers are acceptable
   • Making optional questions mandatory

   Important: When you see a major version change, it means data collected with the old version cannot be properly displayed or analyzed using the new version.

2. Minor changes (Example: 1.0.0 → 1.1.0)

   These changes add new features but don't break existing data:

   • Adding new questions to a form
   • Making validation rules less strict
   • Making required questions optional

   Important: Data collected with older versions will still work perfectly with newer minor versions. However, data collected with newer versions might have extra information that older systems can't handle.

3. Patch changes (Example: 1.0.0 → 1.0.1)

   These are small fixes that don't affect data at all:

   • Fixing typos or improving wording
   • Making visual improvements to the form
   • Adding clarifications to questions

   Important: Patch changes never affect data compatibility in any way.