Ship: versions, reviews, releases

The openFHIR engine records every change to your mappings: which template, context, model or ConceptMap changed, the text that was written, who wrote it and when. Atlas shows that record and lets you push it to a Git repository you own, review changes there, tag releases and compare any two versions.

The Versioning page with the History tab open — a list of recorded changes on the left and the diff of the selected one on the right

The Versioning page of the demo mappings: two changes to the blood pressure model are not pushed yet.

What versioning gives you

History

Every save is a recorded change, also when you didn’t push anything. You can see what a change did, compare it with the current state, and bring an older version back. See History, blame and restoring.

Who changed what

The inspector and the outline show who last changed each mapping, so you know whom to ask. See History, blame and restoring.

A Git repository

The engine pushes the changes as readable commits to a repository on GitHub, GitLab, Gitea or any Git server. Teammates who edit the repository directly can be pulled back in. See Connect a Git repository and Push, pull and conflicts.

Reviews

With the review workflow, changes reach the main branch only through pull requests. See Submit for review.

Releases

A release is a Git tag with release notes and the coverage change since the previous release. See Release a template.

Comparing versions

How much of a template was mapped in one version and in another, and which nodes changed. See Compare two versions.

Export

Any template, live or as of a release, downloads as one ZIP you can upload elsewhere. Export works with or without versioning. See Export and move mappings.

How the pages fit together

Where

What you do there

Versioning in the sidebar (group Track)

The page with the tabs History, Remote, Reviews, Releases and Compare. A count next to the sidebar entry shows the open reviews.

Git remote in the sidebar (group Settings)

Connect the repository, choose the workflow and test the connection.

Engine state, header button Versions

Opens the Versioning page.

Engine state, a selected template

History shows the changes of that template’s OPT, context and models. The ⋯ menu has Release… and Restore from revision… under Versions.

Workspace, top bar

The versioning badge (for example 2 unpushed) opens the History tab of the dock for the open model.

Workspace, inspector

The line under the mapping name says who changed it last; the History footer tab lists the changes behind it.

Workspace, Template tab

Compare with… marks what changed since a release or commit.

The more-actions menu of a selected template with the groups Versions (Release, Restore from revision) and Template (Replace OPT, Delete template)

The ⋯ menu of a selected template on the Engine state page.

The versioning badge

The badge sits in the Workspace top bar and in the header of the Versioning page. It says, in this order of importance:

Badge

Meaning

Status unavailable

Atlas couldn’t read the versioning status. Hover the badge for the reason.

Not versioned

No Git repository is connected yet. The history is still recorded.

Versioning error

The last push (also an automatic one) or the last read of the remote failed. Hover for the error; the Remote tab shows it too.

N in review

The review workflow is on and N pull requests are open.

N unpushed

N recorded changes are not on the remote branch yet.

N to pull, Not synced, Remote changed

The remote branch has commits the engine hasn’t pulled, the engine hasn’t pushed to or pulled from this branch yet, or the branch history was rewritten.

Up to date

Everything is pushed.

In the Workspace a click on the badge opens the History tab of the dock; on the Versioning page it opens the Remote tab. On narrower screens the Workspace shows only the badge’s icon; hover it for the text.

When is versioning available

Note

Versioning is part of the openFHIR engine, not of Atlas. Atlas asks the engine when a page loads and hides Versioning, Git remote, the Versions button, the badge, the History tab and the blame lines when the engine says no. If you open the Versioning or Git remote page anyway, it tells you which of these five situations you are in:

“Versioning is not available in the public demo.”

You are on the public demo portal. It shows the mappings, but nothing is recorded there. Use a sandbox account or your own installation.

“Versioning is turned off on this openFHIR engine. …”

The engine can version mappings, but versioning is off, which is how the engine starts unless told otherwise. Whoever runs the engine turns it on with the setting openfhir.versioning.enabled=true (environment variable OPENFHIR_VERSIONING_ENABLED=true) and restarts it.

“This openFHIR engine does not version mappings. Git versioning needs openFHIR Enterprise.”

The engine Atlas talks to has no versioning at all: it is an open-source engine, or an enterprise release older than versioning. Ask whoever runs your engine to upgrade it.

“Your account may not read the version history (scope versioning.r).”

Versioning is there, but your account doesn’t have the right to read it. Ask your administrator for the versioning.r scope; to push, restore, release or change the settings you also need versioning.w. See Access and permissions.

“The openFHIR engine could not be reached.”

Atlas couldn’t ask the engine at all. The rest of Atlas probably fails too. Try again later, or tell whoever runs the engine.

Atlas asks once per page load, so after your access was changed, reload the page.

The Versioning page saying "This openFHIR engine does not version mappings. Git versioning needs openFHIR Enterprise." with a link "When is versioning available?"

What the Versioning page shows on an engine without versioning. The link leads to this section.