Versioning Guide

Using SmartQC

Product Versioning — User Guide

What is a version?

Every product, raw material, packaging item and environmental monitoring point in the system can have multiple versions. A version is a permanent, uneditable record of what that item looked like at a specific point in time — its field values and, for products, the list of raw materials and packaging it was composed of.

You can think of it like a photograph. Once taken, the photograph does not change even if the original subject changes. Older photographs (versions) remain accessible forever so you can always look back and see exactly what something was at any given time.

Recipes version differently. A production Recipe's formula versions follow their own, simpler lifecycle (Draft → Approved → Obsolete) rather than the one below — see the Manufacturing Guide. The two lifecycles look similar on purpose; they are still two separate things attached to two separate records.


Why versions matter

In a quality control and compliance context, you need to be able to answer questions like:

  • What exactly did batch 2024-07-B of Whole Milk Yogurt contain when we submitted it to the lab?
  • Was Raw Material A at pH 6.5 or 6.7 when we approved Product X version 2?

Versions answer both of these permanently and reliably.


The version lifecycle

A version moves through three stages:

DRAFT  →  APPROVED  →  OBSOLETE

Draft

Your working copy. While a version is in draft, its field values and (for products) composition are simply the item's current, live state — there's nothing separate to edit.

Only one draft is allowed per item at a time.

Approved

The version is locked — a permanent snapshot of every field value and, for a product, every component, exactly as they stood the moment it was approved. Approving automatically retires the previously-approved version (see below). No later change to the item's fields or composition can touch an approved version.

Obsolete

Retired. A version reaches this state when a newer one is approved in its place, or when you retire it by hand. It stays fully on record — snapshot, approver and date included — it has simply stopped being current.


Approving a version

On a product, raw material or packaging dossier, there is no separate "create a draft" step — approving is how a new version comes into being. From the Versions tab, click Approve as v{n}:

  1. A dialog opens showing what changed — a diff against the last approved snapshot (or "No differences from the last approved version" if nothing has moved since).
  2. Add an optional note — this is the only permanent record of why the version was approved, so it's worth a sentence even when the checkbox culture says otherwise.
  3. Click Approve. If there was no draft yet, one is created and approved in the same step; the previously-approved version moves to Obsolete automatically.

The same Approve as v{n} shortcut also appears directly on the Details/Specification tab whenever a field has drifted since the last approved version, so you can catch a record up without leaving the tab you're already looking at.

Environmental points are the one exception. Their dossier still has an explicit New version button, since each version there is a distinct test event rather than a snapshot of an evolving record — see Environmental monitoring points in the Catalog Guide.

Editing a version's note

A version's note can be edited at any status — click it inline on the Versions tab. This is deliberately separate from the version's substantive content: a typo in the note can always be fixed, but the snapshot itself, once approved, cannot.

Deleting a draft

An unapproved draft can simply be deleted — nothing has been locked in yet. This option only appears while the version is still a draft.

Retiring a version

An approved version can be retired by hand, without a newer one replacing it — useful when a version needs to stop being current without another one taking its place yet. It stays fully on record; only its status changes. This is a routine action, not a destructive one, and the confirmation is worded accordingly.

Adding a correction

On a raw material's dossier only, an approved version's row offers Add correction — this doesn't touch the version's own note (which is meant to record why that version was approved). Instead it opens the material's History tab with a note pre-addressed to that version, so a correction is recorded as its own entry rather than rewriting history after the fact.


Products and their components

A product is made up of raw materials and packaging. When you approve a product version, the snapshot records:

  • The product's own field values (e.g. pH, fat %)
  • The complete list of raw materials and packaging at that moment
  • The field values of each raw material and packaging item at that moment
  • Which version of each raw material and packaging was active at that moment

This means the product snapshot is completely self-contained. Even if a raw material is later modified or a new version of it is approved, the product's historical versions remain exactly as they were.

When a component changes

If a raw material used in a product moves to a new approved version, the Composition tab will show the drift — see Reading a dossier in the Catalog Guide for exactly how that surfaces (the same amber drift indicator used for field values). It's a prompt to review, not a requirement to act: if the change is minor, approve a new product version with a note saying so; if it's significant, update the product and go through testing again.

Shared raw materials

The same raw material can be used in multiple products. Each product's approved version captures the raw material at its own snapshot time, independently. Approving a new version of the raw material never retroactively changes any product version that already captured it.


Environmental monitoring points

Environmental versions work slightly differently, as noted above. An environmental monitoring point (a kitchen surface, a water inlet, an air sampling location) does not change in the same way a product does — the point itself stays the same, but it is tested periodically. Each version there represents one test event: v1 might be the January swipe, v2 the February swipe, and so on. Its field values (temperature, sampler name, location notes) describe that specific visit; approving confirms the reading is accepted.


Version history

The Versions tab shows the complete history for the item, most recent first: a status badge and version number, an editable note, and — once approved — who approved it and when (and, while still a draft, who drafted it and when). Obsolete versions stay in the list, fully readable, so you can always go back and see what was recorded at any earlier point.


Frequently asked questions

Can I edit an approved version's snapshot? No. Approved versions are permanent records. To change the item, approve a new version. You can still edit the version's note at any time.

Can I have two drafts at the same time? No. Only one draft is allowed per item at a time.

What happens to my old approved version when I approve a new one? It moves to Obsolete automatically. It remains fully readable in the version history.

Does a component need to be approved before I send a product to the lab? No. You can send a product to the lab regardless of its raw materials' or packaging's version state — the snapshot records the exact state of each component at submission time, so there is always a clear record of what was actually tested.

Can I see what was in a version from years ago? Yes. Click on any version in the history to see its full snapshot — field values, components, and component states — exactly as they were at the time.

↑↓ to move ↵ to open esc to close