Release safe version tags

The Releases tab says, for each repository you release, which version tag is safe to release, and tags it with your release suffix in one press.

On this page

This Sprint → Releases (press 4 on This Sprint) checks the version tags of each repository you release against your tickets, by itself. Releasing a tag ships everything below it, so the candidate is the newest version tag on the default branch where that tag and every tag below it have all their tickets Complete, with no pull request still open for any of them. That is the tag just below the oldest tag that can’t be released. The repositories are picked together, so no ticket is released with only part of its work. Check what the tab lists, then one press tags every candidate as a release, publishes the release notes and comments on each ticket.

Ensemble never cuts a version tag and deploys nothing. Your CI, or a person, tags the default branch. The release tag is what starts your team’s own build.

#What you need

  • A release suffix and a hotfix suffix, in Settings → Releases. Until both are set, the tab shows one line and a Set up in Settings button.
  • The repositories you release, ticked under Released from this workspace in the same settings. Only those are checked. Test and docs repositories you never release stay unticked and are ignored.
  • An issue tracker for the workspace, so pull requests can be joined to tickets. See What you need on the This Sprint page.
  • Push access to a repository to release it.

#What you see

Payments Sprint 24Oct 15 – Oct 28 · day 10 of 14
Latest release: 14 Oct
  • acme/ledgerNo tag since v0.8.0-rc can be released
  • acme/apiChecking…
    Reading main's history: 2,380 of 5,400 commits
  • acme/docs-siteNothing new since v4.1.0-rc

⌃ Show 3 later tickets

    • acme/payments v3.2.0 → v3.2.0-rc · 9f8e7d6 · 15 Oct
    • acme/web v1.8.2 → v1.8.2-rc · 3e2d1c0 · 13 Oct · Latest v1.9.1

⌄ Show 3 earlier tickets

Not in a tag yet

Holding the release

The header

“Latest release: none” or the date of the latest release, for example “Latest release: 12 Nov”. View notes opens the latest release made here: its steps and its notes. Refresh reads the tickets that are not Complete, not read yet or not found from the tracker again, then checks again.

Repositories with no candidate

Above the tickets, a repository you release gets a line only when it has no candidate. Repositories with a candidate are named on the candidate ticket (see below).

  • “No tag can be released”, or after a release “No tag since 0.380.0-rc can be released”.
  • “Checking…”, with a progress bar and one line of what is happening now, for example “Reading main’s history: 1,200 of 5,400 commits” or “Reading tickets from Jira: 300 of 420”. The tab updates by itself until every repository is checked. A candidate is shown once the whole history is read, because a tag far down can still hold one back.
  • “Nothing new since 0.390.0-rc”. This repository is left out of the release.
  • “No version tags on main yet”.

The ticket list

Below the repositories is one list of tickets for all of them, newest tag first. A ticket with work in two repositories is one card. It sits where its latest tag sits, in either repository. The list opens on the newest ticket in the release candidates, marked ★, with one ticket either side. Show 3 later tickets and Show 3 earlier tickets add more each way.

The ★ card names the candidate of each repository, for example “bng-metric-backend 0.316.0 → 0.316.0-rc”, the release tag a release would create, the candidate’s commit (select it to open it on GitHub) and its date, and “Latest 0.418.0” when a newer tag can’t be released yet. One Release… button releases them together.

Each card has a mark:

  • ✓ the ticket is in the release candidates.
  • ✗ in red: the ticket is not Complete, or a pull request for it is still open.
  • ⊘ in amber: the ticket is Complete, but another ticket holds it back.
  • ? on a dashed card: the tracker could not give the ticket, for example because it was deleted. It never stops a release. Check it by hand.

A card shows the ticket’s status, its latest tag in each repository, and one line. On a card that is not in the candidates, the line says what it waits on, for example “Waits on BMD-1061: In Code Review”. Select Show BMD-1061 to go to that ticket. On a card in the candidates, the line says what was done, for example “9 PRs, last merged 23 Oct by robin”.

Below the list, in a separate box, Not in a tag yet lists tickets whose only work is an open pull request, and Holding the release always shows the ticket that stops each repository’s next tag. Pull requests with no ticket are narrow rows between the cards, for example “14 PRs with no ticket · 13 by bots”. Select one to list them. Bot pull requests are left out of these lists unless you tick Show bot PRs at the top of the list. These rows are hidden until you tick Show PRs with no ticket. The marks sit on a line down the left side of the list, with a merge mark for each group of pull requests with no ticket.

Select a card to see its type, its assignee, when its status was last read, and every pull request for it in the repositories you release: open ones, and merged ones with the tag that holds them (or “not in a tag yet”). Open in Jira opens the ticket, and Story opens its story. Select a pull request to open it.

The whole history

There is nothing to pick. The first check of a repository reads the history of main once, from the newest commit back to your last release (or the first commit), with each commit’s pull request — beyond the 90 days Ensemble normally syncs. The tickets are then read from your tracker in batches (Jira: up to 100 in one request). Later checks read only the commits that are new since the last one. It works within your GitHub rate limit and waits when the limit is low.

#The rules

  • A tag’s tickets are everything releasing it would ship: after a release, every ticket merged since that release up to the tag; before your first release, every ticket merged up to the tag.
  • A tag qualifies when each of its tickets is in your Complete column and has no open pull request into the default branch of any repository you release. A ticket in your Cancelled column, such as “Won’t do”, never stops a tag: it is listed with a tick and gets no comment.
  • A ticket the tracker could not find, or has no access to, does not stop a tag. It is listed for you to check. A ticket that is not read yet keeps the row checking; if the tracker does not answer three times in a row, it is listed as “could not be read” instead.
  • Pull requests with no ticket never stop a tag and are not warnings. They are listed between the tickets, and in the notes under untracked or dependency and bot changes.
  • A Complete ticket with work in more than one tag is released whole or not at all. If part of it is above a candidate, in any repository you release, the tags holding the rest can’t be released either, for example “BMD-1048 “Edit an area” would ship without bng-metric-backend #539 (in 0.326.0)”.
  • Commits with no pull request are noted on their tag.
  • Pull requests into a hotfix branch never count.

#Create a release

Release… is on the candidate ticket. It shows only when a repository you can push to has a candidate.

  1. Untick any repository you do not want to release now. The others are released as they are.
  2. Read the release notes, one section per repository, and change them if you want.
  3. Read the comment each ticket will get.
  4. Press Confirm. Ensemble first checks each candidate again: it reads its tickets again, looks for pull requests opened since, and checks each version tag. If anything changed, it stops, lists what changed and writes nothing.

Then, in order: the release tags, a GitHub pre-release on each with that repository’s notes, and a comment on each ticket whose repositories all tagged. The dialog lists each step and whether it worked.