# Versioning **Versioning** (`/versioning`) shows what the engine recorded about every change to the mappings, and what it pushed to your Git repository: the history, the remote branch, reviews, releases, and the coverage of a template between two versions. Each tab is a link of its own (`/versioning?tab=remote`, see {doc}`/reference/deep-links`). The sidebar lists Versioning only when versioning is available: the engine versions mappings, your account may read the history, and you aren't on the public demo. See {ref}`When is versioning available `. Opened anyway, the page says why it can't show anything: ```{figure} ../../images/screens/versioning-unavailable.png :class: screenshot :alt: This openFHIR engine does not version mappings, with a link When is versioning available? The page on an engine without versioning. ``` The other reasons read "Versioning is not available in the public demo.", "Your account may not read the version history (scope versioning.r)." and "The openFHIR engine could not be reached." Until a Git remote is connected, every tab but **History** says "No git remote is connected yet. Connect one to push the history, make releases and compare versions." See {doc}`git-remote`. ## History tab ```{figure} ../../images/screens/versioning-history.png :class: screenshot :alt: The History tab with five changes, the newest selected and its diff The **History** tab with the newest change selected. ``` [1]{.callout} **Versioning** : The page title, with its help link. [2]{.callout} Versioning badge : The state at a glance: **Up to date**, "*N* unpushed", "*N* in review", "*N* to pull", **Remote changed**, **Not synced**, **Not versioned**, **Versioning error** or **Status unavailable**. Point at it for the details; click it to open the **Remote** tab. [3]{.callout} **Git remote settings** : Opens {doc}`git-remote`. [4]{.callout} **History** : Every change the engine recorded, newest first. [5]{.callout} **Remote** : The branch on the Git remote. [6]{.callout} **Reviews** : Pull requests, with the number of open ones. [7]{.callout} **Releases** : Tagged releases. [8]{.callout} **Compare** : A template's coverage between two versions. [9]{.callout} **Checkpoint…** : Records a named checkpoint of the unpushed changes, and can push it right away. With the review workflow, a **Submit for review…** button follows it. See {doc}`/ship/history`. [10]{.callout} Reload [11]{.callout} Change not pushed yet : An orange dot. Each row gives the change's message (or what it did, "Updated model *name*"), the artefact, who made it, when, and where it came from (**Workspace**, **State**, **Terminology**, **Import**…). A chip says when the change is **in review**, **approved**, **changes requested** or in a **review closed** without merging. [12]{.callout} Pushed change : A grey dot. Point at the dot for the commit it was pushed in. **Load older** at the end of the list fetches more. [13]{.callout} **This change** : The diff of the selected change against the version before it. [14]{.callout} **Compared with now** : The diff of the selected version against what the engine has now. [15]{.callout} **Restore this version…** : Previews what bringing this version back would change, then applies exactly that. See {doc}`/ship/history`. [16]{.callout} Diff : Before and after, side by side, with the unchanged lines folded. The same history, limited to the open model, is the **History** tab of the Workspace's Problems dock. ## Remote tab ```{figure} ../../images/screens/versioning-remote.png :class: screenshot :alt: The Remote tab with two unpushed changes and the commits on main The **Remote** tab of a repository with the direct workflow. ``` [1]{.callout} Repository : The remote's URL, with "Checking the remote…" while Atlas asks it. [2]{.callout} State : "Branch *main* · direct push" (or "review workflow"), the last push and its commit, then "*N* changes not pushed yet." or "Everything is pushed." When the remote has moved on its own, an amber sentence says how, for example "main has 2 commits the engine hasn't pulled yet." Errors show in red below. [3]{.callout} **Pull…** : Previews and applies the remote's changes to the engine. Orange when the remote has changes. See {doc}`/ship/push-pull`. [4]{.callout} **Checkpoint…** : As on the History tab. [5]{.callout} **Push** : Pushes the unpushed changes ("Pushing…" while it runs, then "Pushed *N* commits"). With the review workflow, this is **Submit for review…** instead. If the remote changed the same files, Atlas asks which side wins: **Keep the engine's version (overwrite the remote)** or **Take the remote's version (update the engine)**. A push never takes the remote's other changes into the engine: when the branch has changes the engine hasn't pulled, or it was rewritten, Atlas says why, "Pull first, then push.", with a **Pull…** button. On a branch the engine never synced with, it says "Connect the engine to it, or pull first, then push." and offers **Git remote settings** before **Pull…**. On a branch without commits it says "*branch* has no commits (never connected, or deleted)." with a link to the **Git remote settings**, where **Connect** is. [6]{.callout} **Commits on *branch*** : The latest commits on the remote branch. [7]{.callout} Reload [8]{.callout} Commit : Short hash, subject, author and when. [9]{.callout} Kind : How the commit was made (for example **checkpoint**, **import**); ordinary automatic commits have no chip. [10]{.callout} **Restore…** : Brings the engine back to this commit, after a preview. ## Reviews tab ```{figure} ../../images/screens/versioning-reviews.png :class: screenshot :alt: The Reviews tab with an open, a merged and a closed pull request The **Reviews** tab with the review workflow. ``` [1]{.callout} **Reviews** : The count of open reviews. [2]{.callout} **Submit for review…** : Opens a pull request with your unpushed changes. Only with the review workflow; with the direct workflow the tab says "The remote uses the direct workflow; reviews are listed for reference." See {doc}`/ship/reviews`. [3]{.callout} Reload [4]{.callout} State : **open**, **approved**, **changes requested**, **merged** or **closed**, then the title and the pull request number. [5]{.callout} Checks : Green when the checks passed, red when they failed, amber while they run. Point at it for the result. [6]{.callout} Open on the provider : Opens the pull request on GitHub, GitLab or Gitea. [7]{.callout} Branch and files : The review branch and how many files it changes, and the release it belongs to, if any. [8]{.callout} **Add my unpushed changes** : Adds your newer changes to this open review. [9]{.callout} "Create the tag *v1.0.0*" : On a merged release review: creates the release tag. [10]{.callout} **not mergeable** : The provider can't merge the pull request as it is. [11]{.callout} Closed without merging : "Closed without merging: the engine still has these changes, main doesn't (*N* artefacts)." with **Revert the engine to main**, which asks before undoing them in the engine. [12]{.callout} **Resubmit** : On a review closed without merging: opens a new pull request with the same changes. If the provider says the pull request is open or merged after all, the engine refuses and the reason shows above the list. When the merged result differs from the engine, a review says "The merged result differs from the engine for *N* files" with **Take the merged version** and **Keep the engine's**. ## Releases tab ```{figure} ../../images/screens/versioning-releases.png :class: screenshot :alt: The Releases tab with release v1.0.0 of the Blood Pressure template The **Releases** tab. ``` [1]{.callout} Scope : **All releases**, **Whole tenant**, or one template's releases. [2]{.callout} **New release…** : Opens the release wizard for the chosen scope: version, pre-checks, notes and the coverage change. See {doc}`/ship/release`. [3]{.callout} Tag : The release's Git tag. [4]{.callout} Scope : The template it releases, or **whole tenant**. [5]{.callout} Coverage : How much of the template was mapped at this release, and how many elements were newly mapped since the one before ("5/27 mapped (19%) · +5"). [6]{.callout} Open on the provider : Next to who made the release and when. [7]{.callout} **Export ZIP** : Downloads the template as it was at this release. [8]{.callout} **Restore engine to this…** : Brings the engine back to this release, after a preview. [9]{.callout} **Compare with now** : Opens the **Compare** tab with this release and the engine. [10]{.callout} **Copy notes** : Copies the release notes (the button then says **Copied**). ## Compare tab ```{figure} ../../images/screens/versioning-compare.png :class: screenshot :alt: The Compare tab with Blood Pressure from v1.0.0 to now, three newly mapped nodes and a model diff Blood Pressure between release v1.0.0 and the engine now. ``` [1]{.callout} **Template** : The template to compare. [2]{.callout} **From** : **Now (engine)**, a release, a recent commit, or **Other ref…** to type a branch, tag or commit. [3]{.callout} **To** : The same choices. [4]{.callout} Summary : Mapped template elements before and after ("4/27 (15%) → 7/27 (26%)"), or **No coverage changes.** [5]{.callout} Changes : Chips such as "+3 mapped", "−1 lost", "required unmapped 2 → 0", "not modelled 5 → 3" and "*N* template nodes added" or "removed". [6]{.callout} **By archetype** : **Mapped** and **Required unmapped** per archetype, before → after. [7]{.callout} **Changed nodes** : Every template element whose coverage changed. [8]{.callout} Change : **mapped**, **lost**, **changed**, **new node** or **node gone**, then the element and **required** where it applies. [9]{.callout} Model : The model that maps it: click it to see what changed in that model. [10]{.callout} **Open** : Opens the template and model in the Workspace. [11]{.callout} Model diff : The model at **From** and at **To**, side by side. FHIR profiles aren't versioned, so the comparison covers the openEHR template side. See {doc}`/ship/compare`. ## Related - {doc}`/ship/index` - {doc}`git-remote` - {doc}`/ship/history` - {doc}`/ship/push-pull` - {doc}`/ship/reviews` - {doc}`/ship/release` - {doc}`/ship/compare`