## When a new version is needed

| Change                           | Action                       |
| ------------------------------- | ---------------------------- |
| Add a new build requirement     | New version                  |
| Remove a build requirement      | New version                  |
| Change a part on an existing line | New version                  |
| Change a quantity               | New version (significant); in-place edit (clarification) |
| Add or remove a substitute      | In-place edit                |
| Add or change reference designators | New version                |
| Toggle MOA on a line           | New version                  |
| Edit a note or instruction      | In-place edit                |

In general, structural changes (what gets installed, where, and how many) need a new version. Metadata changes (notes, alternates, and clarifications) can be in-place edits.

## Version states

mBOM versions move through:

| State          | Meaning                                                                              |
| --------------- | ----------------------------------------------------------------------------------------- |
| **Draft**      | Editable; not used by any new run                                                     |
| **In Review**  | Submitted for review before release                                                     |
| **Released**   | Locked structure; new runs against the parent part instantiate from this version       |
| **Archived**   | No longer current; preserved for historical reference and in-flight runs that started against it |

Only one version of an mBOM is **Released** at a time. Releasing a new version automatically archives the previously released version.

## Release a new version

1. Open the **mBOM** card on the part page with the version in **Draft**.
2. Make the structural changes.
3. Use the status dropdown to move the version through **In Review** and then **Released**.

The new version becomes **Released**, and the previous version moves to **Archived**. To start the next version once the current one is released, click **Create new mBom version** in the card header.

Group related changes from an Engineering Change Notice into one release rather than several incremental ones. Write a specific release note, such as “Updated R3 to 10kΩ per ECN-2026-0042”, rather than “minor updates”. Don’t edit archived versions, even for typo fixes, since the historical record is part of the audit trail.

## Review and approve a version

A **Draft** version can go through review before it’s released. Reviewers are assigned per role, and each role can require a set number of approvals. Open the review panel from the **mBOM** card:

1. On a **Draft** version, open the review panel and expand the **Reviews** section.
2. Click the add-reviewer control to add a reviewer row. Pick a role, then pick the reviewer (a user or team that holds that role). ION creates an approval request for that reviewer.
3. Resolve any open feedback and assign every required reviewer.
4. Click **Move to In Review** to submit the version. The button is enabled only when all feedback is resolved and every required reviewer is assigned.

Once the version is **In Review**, each assigned reviewer sees the review controls next to a **Review required for role:** prompt naming their role. A reviewer approves or rejects with the approve (check) and reject (X) controls. A reviewer can act only on their own assigned review, and can’t change it after approving. When the required approvals are in, move the version to **Released** with the status dropdown. A reviewer who approved sees a **You approved this as** confirmation with their role on the released version.

## In-flight runs

When you release a new mBOM version, in-flight runs are unaffected:

- Each run captures the mBOM version it was started against at create time.
- Mid-flight runs continue running the old version even after the new one is released.
- New runs started after the release pick up the new version.
- The transition is handled per-run. There’s no way to upgrade an existing run to the new mBOM.

To apply a structural change to an in-flight run, use a [redline](https://docs.firstresonance.io/build-hardware/runs-and-execution/redlines-and-deviations).

## Switch between versions

The **mBOM** card on the part page has a version dropdown (for example, `v1`, `v2`) in its header. Pick a version to view its lines. Each option shows the version’s status, and **Draft** versions can be deleted from the dropdown. To see a version’s full line items, open the full mBOM with the **Go to full mBom** link in the card header.

## Programmatic comparison

ION has no built-in page that diffs two mBOM versions. For integrations or scripts, adapt the [Compare two aBOM versions](https://docs.firstresonance.io/api-reference/examples) query template: fetch the line items for both versions and diff them client-side.