> For the complete documentation index, see [llms.txt](https://support.pears.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://support.pears.io/administration/administration/module-builder/manage-versions.md).

# Manage Module Versions

Module versions allow you to update a module's form structure over time without losing existing response data. Each version is a snapshot of the module's sections, fields, and options. The module detail page displays the version history and provides tools for creating new versions and migrating data.

## Version History

The module detail page lists all versions with their status:

* **Live** — The currently published version.
* **Draft** — A work-in-progress version not yet visible to users.
* **Scheduled** — A version scheduled for future publication.
* **Previous** — Older versions that are no longer live.

Each version entry shows the version number, name, publish date (if applicable), version notes, and the number of responses collected.

## Create a New Draft Version

To update a module's form structure, create a new draft version:

{% stepper %}
{% step %}

#### Navigate to the module detail page

From the Module Builder list, click on the module to open its detail page.
{% endstep %}

{% step %}

#### Click Create New Draft

Click the **Create New Draft** button. PEARS copies the current live version's sections, fields, and options into a new draft.

{% hint style="warning" %}
**NOTE:** You can only create a new draft if no draft currently exists. If a draft is already in progress, edit it instead.
{% endhint %}
{% endstep %}

{% step %}

#### Edit the draft

The new draft opens in the [form builder](/administration/administration/module-builder/build-a-form.md). Make your changes — add, remove, or modify sections and fields as needed.
{% endstep %}

{% step %}

#### Publish the draft

When the draft is ready, [publish it](/administration/administration/module-builder/publish-a-module.md) to replace the current live version.
{% endstep %}
{% endstepper %}

## Migrate Response Data

When you publish a new version that changes the form structure, existing responses remain associated with the version they were created on. Data migration allows you to move responses from an older version to a newer version, mapping fields between the two.

{% stepper %}
{% step %}

#### Start a migration

From the module detail page, click **Migrate Responses** on the version you want to migrate data from.
{% endstep %}

{% step %}

#### Select records

Choose which responses to include in the migration. You can select all responses or pick specific records.
{% endstep %}

{% step %}

#### Configure field mappings

Map fields from the source version to fields in the target version. PEARS automatically maps fields with matching slugs. For fields that changed between versions, manually select the corresponding target field.
{% endstep %}

{% step %}

#### Review and confirm

Review the migration summary showing the number of records and field mappings. Click **Confirm** to start the migration.
{% endstep %}
{% endstepper %}

{% hint style="warning" %}
**NOTE:** Publishing a new version cancels any pending migrations for the module. Complete all migrations before publishing a new draft.
{% endhint %}

## Copying Records Across Versions

When a custom module record is copied, the new record is created on the module's **current live version** rather than the version the source record was attached to. This keeps copies aligned with the latest form structure as the module evolves.

* If the live version added new required fields, the copy is marked **Incomplete** so you can open it and fill in the new fields before marking it complete.
* If the live version dropped a section that the source record had data in, the copy form shows a warning before you proceed so you know that data will not carry over.
* Editing, viewing, and deleting existing records continues to use the version each record was originally attached to — only **Copy** lands on the live version.

## Delete a Version

To delete a previous version, click **Delete** on the version entry in the module detail page. Deleting a version removes the version record but does not affect responses that have been migrated to other versions.

{% hint style="warning" %}
**NOTE:** You cannot delete the live version. To remove the live version, unpublish it first or publish a new version to replace it.
{% endhint %}