Releases and the project 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, 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).

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›, then This project›, then 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›, then This project›, then 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 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.

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 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›, then This project›, then 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: link cycles to a release so it fills itself.
• Plan testing for a release or cycle: what has to pass before the release ships.
• Pull requests: the merges a release’s notes cite.