Versions is currently in beta. Contact your TAM for access.
Version control allows you to track the history of changes for a particular input, with the ability to name important checkpoints and restore from a prior version. Every save creates a new version automatically, so you can experiment with confidence and roll back when something goes wrong.
This article covers what a version is, how to access the version history, how to name and annotate versions, and how to restore from a historical version.
Overview
A version is a complete snapshot of an inputs at a single point in time. Every version stores:
- The full configuration of the input:
- Name and description: The input's name and description.
- Type: The input's type (eg. text box, select dropdown, etc)
- Query and data source: The query body, query settings, and the data source the query runs against.
- And version metadata:
- Author and timestamp: The user who created the version and the moment it was saved.
- Version title and message: Any custom title and description you've added (see Managing Versions).
At any moment, exactly one version is the Live Version. This is the version that will run when the input is used in a generation. Every other version is a historical version, preserved for review and restore.
Matik creates versions automatically. You don't need to take any action to start tracking history. Every save of an input demotes the previous Live Version to a historical version and creates a new Live Version with your latest changes.
Versions are immutable. Once created, the configuration captured in a historical version never changes. Only the version metadata (version title and description) can be edited.
Viewing Version History
You can track and manage versions from the Version History. To open Version History from the input form, go to the three-dot actions menu and select Show Version History.
Note: Version History only appears for an input that has been saved at least once. If you're creating a brand new input, save it first to start tracking history.
The panel lists versions in reverse-chronological order, with the Live Version at the top and historical versions below.
Each version in the list shows the following information:
- Live Version badge: The Live Version is labeled with a Live Version badge. This is the version that will be used for generations.
- Title: Your custom version label, or an auto-generated title if you haven't named the version. (see Version Names).
- Description: Your custom version description, or an auto-generated description if you haven't added one.
- Author: The user who saved this version.
-
Relative timestamp: How long ago the version was created (e.g.,
3 hours ago,2 days ago).
Restoring from a previous version
Restoring brings back the configuration of a historical version. The original historical version stays in the timeline. Restore creates a new Live Version that mirrors the historical one, so your full history is preserved.
To restore a historical version:
- Open the Version History panel.
- Find the historical version you want to restore.
- Click the menu icon (⋯) and select Restore this version.
- Confirm and click Restore.
A new Live Version is created, matching the configuration of the historical version you restored from.
Managing Versions
Any admin with edit access to the input can name versions, restore from versions, or delete versions.
Version Cleanup
For performance reasons, Matik does not retain version history forever. Matik will clean up versions after a certain time frame.
- Unnamed versions will be discarded after 3 months.
- Named versions will be discarded after a year.
Version Title and Descriptions
When you haven't given a version a custom title or description, Matik generates one for you so the history is always readable at a glance. The auto-generated title is composed of the type of change followed by the date and time, and the description summarizes what changed.
Default title
The default title is populated based on the type of change that was made:
| Event | Default title |
|---|---|
| The input was first created |
Created • Mar 14, 2:30 PM
|
| The input was edited and saved |
Updated • Mar 14, 2:30 PM
|
| The input was restored from a historical version |
Restored • Mar 14, 2:30 PM
|
Default descriptions
The default description is populated based on what was changed:
| Event | Default description |
|---|---|
| Created |
Input was created
|
| Updated (with known changed fields) |
Query, Description was updated — the fields you changed
in this save, listed by name.
|
| Updated (no specific fields recorded) |
Input was updated
|
| Restored from a named version |
Restored from “Q3 baseline” — uses the label of the
version you restored from.
|
| Restored from an unnamed version |
Restored from a previous version
|
If you've added a custom title or description, your text replaces the default in the panel.
Naming Versions
You can also name a version, customizing the title or description yourself.
- This can help make important checkpoints easy to find later. For example, if you're about to make a significant change to the input, you can name the current version
Pre-Edit - validated queryso that you can easily find and revert to it if needed. - Additionally, you can name versions to maintain change history. Named versions will be retained longer than unnamed versions. (See Version Cleanup.)
To name a version or edit its description:
- Open the Version History panel.
- Click the menu icon (⋯) on the version you want to edit.
- Select Name this version for an unnamed version, or Edit version info for a version you've already named.
- In the Edit version information modal, fill in the fields:
- Title: A short label for the version. Limit 255 characters.
- Description: Longer commit-message-style notes about what changed and why. Limit 2,048 characters.
- Click Save.
Deleting versions
If desired, you can also delete versions to clean up the list. To delete a version, go to the three-dot menu for a given version and select Delete version.
Note: you cannot delete the Live version. Instead, you can delete the input itself.
Best practices
- Name your checkpoints. Before any significant change (eg. refactoring a query, switching data sources, restructuring inputs) name the current version with a clear label. Future-you will thank you.
- Use descriptions to explain why. Auto-generated titles tell you what changed. A short description telling teammates why the change was made makes the history more useful when collaborating.
Comments
0 comments
Article is closed for comments.