# Release a template ## What you'll do You tag a release of one template, or of all mappings of the tenant: a Git tag with a version, release notes, and the coverage change since the previous release. Systems that load mappings from the repository can then pin that release, and you can export it, restore it or compare with it. ```{figure} ../images/ship/release-wizard.png :class: screenshot :alt: The dialog "New release · Blood Pressure" with the checks, the version 1.1.1, the model versions choice and the release notes The release wizard for the Blood Pressure template. ``` ## Before you start - A Git repository is connected: see {doc}`git-remote`. Provider releases (a release page on GitHub, GitLab or Gitea) need a provider; without one, only the tag is created. - You need the `versioning.w` scope. **Set the changed models to this version** and **Increment the changed models' versions** also change the mappings, so they need write access to them. ## Steps 1. Start the wizard: - for one template: on the Engine state page select the template, open **⋯** and choose **Release…** (under *Versions*); - or on the **Releases** tab of the Versioning page: pick the scope in the list (**Whole tenant**, or a template; **All releases** means the whole tenant) and click **New release…**. The title says what is released: *New release · Blood Pressure*, or *New release · all mappings*. *Preparing the draft from the remote…* shows while the engine prepares it. 2. Read the **Checks**: | | Check | | |---|---|---| | [1]{.callout} | Unpushed changes | *Everything is pushed.*, or *N changes not pushed — the release only contains pushed changes.* Click **Push now** to push them first. | | [2]{.callout} | Open reviews | *No open reviews.*, or *N open reviews — not part of this release.* | | [3]{.callout} | Problems | *No problems in the mappings.*, or *N errors, N warnings in the mappings.* (the problems of the saved mappings, as the Problems dock lists them; see {doc}`/check/fix-problems`). | Below the checks: *Since \: N added · N changed · N removed · by …*, the people whose changes the release contains. 3. Check the **Version** [4]{.callout}. The engine suggests one from the changes since the previous release: a removed file raises the major version, an added one the minor, a changed one the patch. Any version like `1.2.0` is accepted (a leading `v` is dropped). 4. Choose **Model versions** [5]{.callout}: - **Leave as they are** (default); - **Set the changed models to this version**: the `metadata.version` of each model and context changed since the previous release becomes the release version; - **Increment the changed models' versions**: each changed model's own version goes up by the same level as the release (versions that aren't like `1.2.0` stay as they are). 5. Edit the **Release notes (Markdown)** [6]{.callout}. They start with the engine's draft: the added, changed and removed files, the checkpoint messages, restores and contributors. When there is a previous release, Atlas appends a *Coverage* section (*Computing the coverage change…* while it works): mapped nodes and required unmapped nodes then and now, the changes, and the newly mapped and no longer mapped nodes. 6. Click **Create release** [7]{.callout}. *Creating the release (tag, notes, provider release)…* shows while it works. ```{figure} ../images/ship/release-result.png :class: screenshot :alt: The dialog "Release created" — Tagged blood_pressure/v1.1.1 at a90d4e2, Open on the provider, and a version bump table updating the blood pressure model The release is tagged; the changed model got the release version. ``` The result says *Tagged \ at \.* with **Open on the provider**, and, if you chose to change model versions, the **Version bump** it made. With the review workflow the version bump goes through a pull request instead: *The release waits for its pull request to be merged; the tag \ is created then.* Once it is merged, the review on the **Reviews** tab offers **Create the tag \** (see {doc}`reviews`). ### Tag names | Released | Tag | |---|---| | All mappings of the tenant | `v1.2.0` | | One template | the template's key and the version, for example `blood_pressure/v1.2.0` | ### The Releases tab ```{figure} ../images/ship/releases-tab.png :class: screenshot :alt: The Releases tab listing blood_pressure/v1.1.0 with "6/27 mapped (22%) · +2", blood_pressure/v1.0.0 and v1.0.0 for the whole tenant The releases of the demo mappings. ``` | | | |---|---| | [1]{.callout} | Which releases to list: **All releases**, **Whole tenant**, or one template. | | [2]{.callout} | **New release…** for the scope picked in [1]{.callout}. | | [3]{.callout} | The coverage stored with the release: mapped nodes of the template, and how many were newly mapped since the release before. | | [4]{.callout} | **Export ZIP**: download the template as of this release (template releases only, see {doc}`export`). | | [5]{.callout} | **Restore engine to this…**: bring the engine back to this release (see {doc}`history`). | | [6]{.callout} | **Compare with now**: open the **Compare** tab from this release to the engine (see {doc}`compare`). | | [7]{.callout} | **Copy notes** copies the release notes; it reads *Copied* for a moment. | The arrow icon opens the release on the provider. ## Check it worked - The release is at the top of the **Releases** tab with its notes. - **Open on the provider** shows the tag (and, with a provider, its release page). ## Tips :::{tip} Check coverage before you release: the *Coverage* section in the notes tells readers what the release adds. See {doc}`/check/coverage`. ::: :::{tip} Releasing one template keeps its versions independent of the other templates of the tenant. Restoring or exporting a template release touches only that template. ::: ## Watch out :::{warning} Changes not pushed and open reviews are not part of the release. Push them, or merge the reviews, before you create it. ::: :::{warning} A version that already exists as a tag can't be released again. Pick the next version. ::: ## If something goes wrong | Message | What to do | |---|---| | *A version like 1.2.0* | The version isn't valid; **Create release** stays disabled. | | *Coverage unavailable* (hover for the reason) | The coverage change couldn't be computed; the release still works, without that section. | | *Could not prepare the release draft* | The engine couldn't read the remote; check the {doc}`git-remote` page. | | *Could not create the release*, or the engine's reason (for example that the tag exists already) | Fix the cause and try again. | | *No API base URL is stored for \, so reviews and releases can't reach it.* | Fix it on the {doc}`git-remote` page. | See {doc}`/reference/messages` for the rest. ## Related - {doc}`compare`: compare a release with another version or with now. - {doc}`export`: download a release as a ZIP. - {doc}`/reference/screens/versioning`: the Versioning page, control by control.