> 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

Create new module versions and migrate response data between versions in PEARS.

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 shows the module's versions in two places:

* **Status card** — Shows the newest version's number and whether the module is live, has a draft in progress, or is scheduled to go live on a future date. Its button opens the next action: **Create New Draft**, **Edit Draft Version**, **Edit Draft**, or **Edit Published**.
* **Previous Versions** — Lists older versions that are no longer live. Each entry shows the version number, name, and the number of responses collected, with an actions menu for migrating responses or deleting the version.

## 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 to open the [Setup](/administration/administration/module-builder/module-setup.md) page for the new version. Review the module details and version notes, then click **Save and Continue**. 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 or scheduled version currently exists. If one 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 the current live version. PEARS matches sections, fields, and options between the two versions automatically.

{% stepper %}
{% step %}

#### Start a migration

From the module detail page, find the version you want to migrate data from under **Previous Versions**, open its actions menu, and click **Migrate Responses**. This option appears only for versions that have responses.
{% endstep %}

{% step %}

#### Select records

Choose which responses to include in the migration. Check **Select All Records** or pick specific records, then click **Next**.
{% endstep %}

{% step %}

#### Configuration

Choose whether to **Mark migrated records as incomplete** (the default is **Yes**) so users can update them later. If you mark them incomplete, also choose whether to **Notify users if record marked incomplete**. Click **Next**.
{% endstep %}

{% step %}

#### Review and migrate

Review the summary, which shows the version history, the number of fields and records that will be modified or marked incomplete, and tables of the sections, fields, and options that will be added or removed. Click **Migrate Records** to start the migration.

{% hint style="warning" %}
**NOTE:** Migrations are final and cannot be reverted.
{% endhint %}
{% endstep %}
{% endstepper %}

{% hint style="warning" %}
**NOTE:** Publishing a new version cancels any pending migrations for the module, and so does starting another migration. Complete each migration before starting the next one or 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.

* Every copy starts **Incomplete**, so you can open it, fill in any fields the live version added, and mark each section 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, open its actions menu under **Previous Versions** on the module detail page and click **Delete**. Only versions with no responses can be deleted, so migrate a version's responses to the live version first. Deleting a version 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 %}