# Pipeline versioning

Versioning is a fundamental part of the development lifecycle. It allows you to track changes, recover previous states, and manage the integration lifecycle across different environments (Test, Prod).

## Version architecture: Major and Minor

Digibee uses a simplified semantic versioning model based on two levels (X.Y):

<table data-full-width="false"><thead><tr><th>.</th><th>Major Version (X.0)</th><th>Minor Version (0.Y)</th></tr></thead><tbody><tr><td><strong>Impact</strong></td><td>Significant (structural or critical changes).</td><td>Incremental (adjustments, fixes, or optimizations).</td></tr><tr><td><strong>Concurrency</strong></td><td>Allows multiple active versions in parallel.</td><td>Only one active version at a time per environment.</td></tr><tr><td><strong>Creation</strong></td><td>Always manual.</td><td>Automatic (upon saving a previous deployment) or Manual (via history).</td></tr></tbody></table>

### Major versions (X.0)

**Major** versions are the primary versions of a pipeline, intended for deep structural changes. They organize the project lifecycle by grouping respective Minor versions into distinct histories. You can keep multiple Major versions of a pipeline running simultaneously.

* **When to use:** Changes to the input/output contract, complex new features, or modifications that require consuming systems to adapt to avoid integration failures.
* **Numbering logic:** If the current version is 1.5, creating a Major version results in 2.0.

#### How to create a Major version

1. In the Digibee platform, go to the **Build** screen.
2. Locate the desired pipeline using the search bar.
3. On the pipeline card, click the **Options** menu (three dots) and select **New version**.
4. Confirm the action in the security pop-up by clicking **Create version**.
5. Make your changes in the Canvas and click **Save**. The pipeline is now ready for deployment.

### Minor versions (0.Y)

**Minor** versions are secondary iterations focused on continuous improvements within the same Major lineage. Unlike Major versions, the system does not allow the simultaneous execution of two Minor versions (for example, 1.1 and 1.2) in the same environment.

The platform automatically generates a new Minor version when you save the pipeline, provided the current version has already been deployed.

* **When to use:** Bug fixes (hotfixes), performance optimizations, or logic adjustments that do not change the pipeline's communication interface.
* **Numbering logic:** If the current version is 1.1, the new Minor will be 1.2.

#### How to create a Minor version (via history)

In addition to auto-saving, you can create a new Minor version from an old version, provided it is not archived.

1. On the pipeline card (**Build** screen), click the **Options** menu (three dots) and select **View history**.
2. In the **Actions** column, click the **plus sign (+)** to generate a new Minor version.
3. Make the necessary changes in the pipeline and click **Save**.

## Pipeline version history and management

The pipeline version history lists all minor versions associated with a specific major version. Here, you can see who modified the pipeline and check the deployment status per environment.

1. On the pipeline card (**Build** screen), click the **Options** menu (three dots) and select **View history**.
2. The history displays the following fields:
   * **Version:** Numerical identifier (X.Y).
   * **Author:** Name and email of the user responsible for the last modification.
   * **Date/Time:** Timestamp of the last update.
   * **Description:** Notes regarding the changes made.
   * **Actions:** Available commands for that specific version.

You can also choose the number of versions displayed per page and navigate the history using the pagination tool in the bottom right corner.

#### Available actions

* **Edit (✏️):** Modifies the latest Minor version (if not archived). Structural triggers and connectors cannot be edited in this view.
* **View (👁️):** Opens the pipeline in read-only mode in the Canvas.
* **Archive (🗃️):** Removes the version from the main view on the Build page. Digibee pipelines are not permanently deleted to ensure data integrity.
* **Restore (🕐):** Reactivates a previously archived version.

{% hint style="info" %}
Records prior to Feb 01, 2022, may display "No data" in the author field. Dates shown as Dec 31, 1969, indicate a lack of metadata in pipelines created before Feb 15, 2021 (Unix system default).
{% endhint %}

## Visual Diff (Version comparison)

To facilitate troubleshooting and code review, the Visual Diff tool allows you to compare two minor versions of deployed pipelines side-by-side.

1. Go to the **Run** page and locate the pipeline.
2. In the three-dot menu, select **Open differences between versions**.
3. Select the pipeline versions you wish to compare.
4. Select the **more recent** version on the left side and the **previous** version on the right side.
5. Click on individual pipeline steps to view changes in connector configurations. Added or removed steps are color-coded: <mark style="background-color:$success;">**green**</mark> for additions and <mark style="background-color:$danger;">**red**</mark> for removals.

The left sidebar displays the count and type of changes:

* **Added components:** Number of new elements in the flow.
* **Removed components:** Number of elements missing from the latest version.
* **Modified components:** Number of internal configuration changes (parameters, expressions, triggers) and link changes between elements.
* **Summary of changes:** Total count of added, removed, or modified steps.