# Releases and the project changelog

> Group the tickets that ship together into a release, write its notes, check it's ready, ship it, publish it to GitHub, and keep the project's changelog.

This page shows you how to take a set of tickets from planned to shipped as one release. By the end you'll know how
to create a release and fill it, generate and polish its notes, check it's ready, ship it (and undo a ship), publish
it to GitHub, and where shipped releases are listed.

A release groups the tickets that go out together, such as "v1.4.0" or "Q4 Ship — Payments". It has a status, a
target date, notes written from its finished tickets, and the deploy steps its migrations need. A ticket can be in
several releases. Shipping a release marks it released, publishes its notes and adds it to the project's changelog,
so the changelog is a running record of what went out and when.

If the project runs [cycles](https://docs.bydawn.com/cycles/), releases can ride them: link a cycle to a release and the cycle's tickets
join it.

## The Releases page

Open **Releases** from the project's sidebar, or press `⌘6`. When the project runs cycles, the row
reads **Cycles & Releases** and opens on cycles, with **Releases** as the next tab. Open releases come first, soonest date on top, then the ones that shipped or were
canceled. Each row shows the release's version, date, status and how many of its tickets are done.

With cycles on, the page has two layouts. **List** is the table. **Train** draws the project's cycles along a
timeline, with each release riding the cycles linked to it up to its release date. A release with neither a cycle
nor a date waits under **Unscheduled**.

## Create a release

1. On the Releases page, choose **New release**.

2. Fill in the form:
   - **Name** (required).
   - **Version**: By Dawn suggests the next one under the project's version scheme. Type over it to use your own.
   - **Release date**: the day you plan to ship.
   - **Status**: leave **Default status** for the project's planned status.
   - **Colour** and **Description**, both optional.

3. Choose **Create release**. The release's page opens.

**Edit** on the release's page changes any of these later. **Delete** removes the release with its notes and
deployment documents, but keeps its tickets.

### Add tickets

On the release's **Overview** tab, **Assigned issues** lists its tickets. **Assign issues…** adds more: search by
key or title, or type a ticket key to add one the list hasn't loaded. The menu stays open, so you can add several in
one go. The × on a row takes a ticket out of this release only.

You can also add from elsewhere:

- **On a ticket**, the release sits in the header. It reads **Add to release** when the ticket has none, and you can
  tick more than one.
- **On the board**, select several cards and use **Add to release**.

## Link cycles

With cycles on, the **Overview** tab starts with **Cycles**: one chip per linked cycle, with its dates and how far
along it is. **Link cycle** adds one of the project's running, upcoming or three most recent cycles. Every ticket in
a linked cycle joins the release, and tickets added to the cycle later join too. Those rows say where they came
from, such as **via Cycle 13**, or **carried over from Cycle 12** for a ticket rolled over unfinished.

The × on a cycle chip unlinks it. The tickets that came in through that cycle leave the release, and the dialog says
how many. Tickets you added by hand stay. If you take a cycle's ticket out by hand, it stays out: the cycle won't add
it back.

A cycle's own page can link and unlink too (see [Cycles](https://docs.bydawn.com/cycles/#cycles-and-releases)).

## Statuses

A release's status shows as a coloured dot and name. Change it with **Status** on the release's page. Statuses are
yours to name, and each can carry a role that tells By Dawn what it means: **Planned**, **Active**, **Released** or
**Canceled**. A release in a Released or Canceled status is closed, so it can't take new work or be shipped again.

Statuses are set in **Settings › This project › Releases**, under **Release statuses**. A project uses the
organization's statuses until a workspace admin chooses **Customize for this project**, which copies them so this
project can add, rename, recolour, reorder and delete its own. Deleting a status that still holds releases asks where
they should move.

## Release notes

The **Notes** tab holds the release's notes. **Generate notes** writes them from the release's finished tickets,
filed under headings by label, citing the merged pull requests behind them. Tickets that aren't finished are left out and
listed under **Not in this release**, so nobody wonders where they went.

Generated notes refresh themselves as the release's tickets change, until someone edits them. After that they stay
as written. If the tickets change after an edit, the tab shows **Stale since edit.** with **Regenerate**, which asks
before replacing your edits.

From the tab you can also:

- **Edit** the notes as Markdown, then **Save notes**.
- **Copy markdown** or **Download .md**.
- Switch to **Diff vs published** to see what changed since the notes were last published.

### Polish with an agent

**Polish with agent** asks an agent to rewrite the notes as customer-facing copy. It runs as a worker on a ticket of
its own: **View run** opens that ticket, and **Cancel** calls the polish off. Its result never replaces your notes on
its own: it appears beside them as **Draft from agent**, and you choose **Accept**, **Edit first** or **Discard**. If
the notes changed while the agent worked, accepting asks first, because the draft would replace that change.

### Note sections

The headings come from **Settings › This project › Releases**, under **Release note sections**. Each section
lists the labels filed under it, and a ticket goes under the first section, top to bottom, that has one of its
labels. A ticket with none of them goes under "Other changes". Order matters, so drag sections to reorder them. Each
section also has an audience: **Customer**, **Internal only** or **Hidden**. As with statuses, a project uses the
organization's sections until a workspace admin chooses **Customize for this project**. Notes nobody has edited pick up a
change to the sections on their next read.

## Migrations and deployment documents

The **Migrations & deploy** tab is for whoever deploys the release:

- **Readiness**: the release's checks at a glance, with a verdict of **Ready to ship**, **Ready, with warnings** or
  **Not ready to ship**.
- **Schema migrations**: the migrations the release's tickets declare, in the order they should land, each marked
  **Landed** or **Not landed**.
- **Deploy runbook**: deploy steps By Dawn writes from those migrations. It's read-only because By Dawn rewrites it as the
  migrations change, but you can copy or download it.

Anything you write yourself goes on the **Documents** tab, under **Deployment notes**: a runbook, a migration
checklist or a rollback plan. **Add document** creates one. Regenerating the notes never touches these.

## Test the release

The release's **Tests** tab shows its test plan: the suites to launch and the cases to run by hand before it ships.
With no plan yet, **Draft a test plan** has By Dawn draft one from the cases linked to the release's tickets, your
regression suites and what failed last time. Once there's a plan, the tab shows its pass rate, its failed, blocked
and untested checks and each item's status, and **Open in Tests** opens it to edit. [Plan testing for a release or
cycle](https://docs.bydawn.com/test-plans/) covers the rest.

## Ship a release

**Ship** on an open release's page opens a check before anything changes. It marks the release Released, publishes
its notes and adds it to the changelog.

1. Read **Ready to ship?** It shows how many issues are done and a line for each check: unfinished issues, open pull
   requests, failing CI, unlanded migrations, release notes, the deploy runbook and the release's
   [testing](https://docs.bydawn.com/test-plans/#is-the-release-ready).

2. If some issues aren't finished, choose where they go. The default follows the project's setting, or pick another
   open release, or keep them in this one.

3. Confirm with the button that names the release, such as **Ship v1.4.0**. A check that warns doesn't stop you. A
   check that fails does: a pull request that isn't merged, or one whose CI is failing. To ship regardless, tick
   **Ship anyway**, and the button becomes **Ship v1.4.0 anyway**. A closed [test gate](https://docs.bydawn.com/test-plans/#the-test-gate)
   is the exception: **Ship anyway** doesn't get past it.

### Undo a ship

For 10 minutes after a ship, a bar at the bottom of the app offers **Undo** with a countdown, and the release's page
shows **Undo ship**. Undo puts the release back as it was before the ship, and returns any carried-over tickets to
the releases they were in. The offer lives in the browser you shipped from: it survives a reload there, but
another computer won't show it.

### Publish without shipping

**Publish** snapshots the notes as they stand without changing the release's status. The notes stay editable, and
**Diff vs published** compares against that snapshot. **Unpublish** takes it back.

## Publish to GitHub

**Publish to GitHub** puts the release on your GitHub repos, as the By Dawn GitHub App.

1. Under **Repos**, tick the repos. The ones the release's pull requests touched are ticked for you.

2. Choose **GitHub release** (a release page with the notes, and its tag) or **Tag only**.

3. Check **Tag**, which starts as the release's version. For a GitHub release, you can tick **Draft** or
   **Pre-release**.

4. Choose **Publish**.

The tag points at each repo's default branch as it is at that moment. Each repo answers on its own, so the dialog
ends with a result per repo: **Published**, **Notes updated**, **Tag already there**, **Permission missing**,
**Not on GitHub** or **Failed**. Publishing to a repo again keeps its tag and updates its GitHub release with the
current notes. The release's page lists where it was published under **GitHub**.

## Release settings

**Settings › This project › Releases** has a **Release settings** card for project admins and org admins:

| Setting | What it's for |
|---|---|
| **Release cadence** | **Manual**, or have By Dawn plan a release for **Every cycle** or **Every few cycles**. Needs cycles. |
| **Version scheme** | **Semantic (1.4.0)**, **Calendar (2026.10)** or **Free text**. Decides the version a new release is offered. |
| **Offer to ship the linked release** | Completing a cycle offers to ship its unshipped release. Needs cycles. |
| **Link the next cycle to the release** | The next cycle also feeds an unshipped release. Needs cycles. |
| **Unfinished tickets’ releases** | The default when completing a cycle with unfinished tickets in its release. Needs cycles. |
| **Unfinished tickets** | Where a shipped release's unfinished tickets go: **Move to the next release** or **Leave them where they are**. |

The semantic scheme bumps the latest version: major when a ticket is labelled breaking, minor for feature, patch
otherwise. "The next release" is the project's next open, unshipped release by date. If there isn't one, the
tickets stay where they are, and the ship dialog says so.

## The changelog

The **Changelog** tab, beside **Releases**, lists every shipped release, newest first, with its notes as they were
published. It's the page to send someone who asks what changed.

- **Copy** on an entry copies that release as Markdown.
- **Copy all** copies the whole changelog as one Markdown document, and **Download .md** saves it as a file. Both
  include every release, not only the ones loaded on screen.
- **Open release** goes to the release's page.

In the Markdown, each release is a heading with its version, name and ship date, and its own note headings sit one
level below it. That way the file drops into a repo as a CHANGELOG without rework.

## Do and don't

- **Do label tickets before you generate notes.** Labels decide which section a ticket lands in, and anything
  unlabelled ends up under "Other changes".
- **Do edit notes after the release's tickets have settled.** Once edited, notes stop refreshing, so a late change
  to the tickets means regenerating and losing the edit.
- **Don't publish to GitHub before the code is merged.** The tag points at the default branch as it is when you
  publish, so unmerged work isn't in it.

## FAQ

**What's the difference between Publish and Ship?**

**Publish** only snapshots the notes. **Ship** marks the release Released, publishes its notes, adds it to the
changelog and moves its unfinished tickets on.

**Can a ticket be in more than one release?**

Yes. Taking it out of one release leaves the others alone.

**I shipped too early. Can I take it back?**

Within 10 minutes, use **Undo** from the browser you shipped from. That's the one-step way back, so read the
readiness checks before you ship.

**Do I need cycles to use releases?**

No. Releases work on any project. Cycles add the cycle links, the **Train** layout, the release cadence and the
offer to ship when a cycle completes.

## Next

- [Cycles](https://docs.bydawn.com/cycles/): link cycles to a release so it fills itself.
- [Plan testing for a release or cycle](https://docs.bydawn.com/test-plans/): what has to pass before the release ships.
- [Pull requests](https://docs.bydawn.com/pull-requests/): the merges a release's notes cite.

Source: https://docs.bydawn.com/releases/