Branches and releases

How a change travels from your branch to an installed Atlas. One shared branch, titles that decide the version, and releases a bot prepares.


Atlas is trunk-based. There is one shared branch, main, and every pull request targets it. A release is not a branch. It is a tag: a fixed bookmark on one commit of main.

Two words this page leans on:

  • A branch is a name that points at the newest commit in a line of work. It moves forward as commits are added.
  • A tag is a name for one commit, and it never moves. alpha-0.6.0 always means the same snapshot.

The whole picture

  you/fix-sidebar ──┐     sam/vim-keys ──┐     you/paste-images ──┐
                    ▼                    ▼                        ▼
  main ──●──────────■────────────────────■────────────────────────■──────►
                    │                    │                        │
                    └──────────┬─────────┴────────────────────────┘
                               ▼
                 ┌──────────────────────────────┐   merge it when
                 │ PR: chore: release 0.6.0     │   you want to ship
                 │  version, CHANGELOG.md       │ ─────────────────►  tag alpha-0.6.0
                 │  (kept up to date by a bot)  │                     + installers
                 └──────────────────────────────┘

Everyone merges small pull requests into main. A bot keeps a release pull request open that describes what would ship. Merging that pull request is the release.

Why not version branches

Until November 2026, Atlas collected work on a branch named for the next version (0.4.1) and merged that branch into main to release:

  BEFORE                                    NOW

  feature ─┐                                feature ─┐
  fix ─────┼─► 0.4.1 ──► main               fix ─────┼─► main ──●──●──●──►
  thing ───┘    │                           thing ───┘             │  │
                └ number chosen before                   alpha-0.6.0  alpha-0.6.1
                  anyone knew what was in it              (number chosen at release)
  • The version number was fixed when the branch opened. Moving to the next one meant a new branch and retargeting everyone's pull requests, so it rarely happened: 0.4.1 collected a month of work and shipped twice under the same number.
  • The auto-updater only offers a version strictly newer than the installed one, so the second 0.4.1 build never reached anyone who had the first.
  • Every contributor first had to work out which branch was current.

Now the number is chosen when you release, from what actually landed.

The life of a pull request

  1. branch off main          2. work, push, open a PR      3. merge (a merge commit)
                                                              (branch is deleted)
  main ──●──●                     you/fix-sidebar
            └──► you/fix-sidebar   ●──●──●──●  ──► PR ──►  main ──●─────────■
                                                                   \       /
                                               your commits, kept   ●──●──●
                                                                            ▲
                                              a merge commit, titled with
                                              the PR title: "fix(sidebar): …"
  1. Branch from main as <you>/<short-slug>. Keep it to days, not weeks: a long-lived branch drifts away from everyone else's work.
  2. Push and open a pull request against main.
  3. When CI passes and it's reviewed, it is merged with a merge commit. Its commits land on main as they are, joined by one merge commit, and its branch is deleted. Pull requests are not squashed.

main must stay shippable

Anything merged can go out in the next release. Unfinished work waits on its branch, or lands switched off behind a setting until it's ready.

Pull request titles

The merge commit is titled with the pull request title, and the commit messages on main decide the next version and fill the changelog. So titles follow Conventional Commits, and a check on every pull request enforces it:

  type(scope): what changed, in the present tense
  ────  ─────  ──────────────────────────────────
   │      │      └─ what a user or a teammate would notice
   │      └──────── optional: the area (chat, terminal, settings, …)
   └─────────────── feat · fix · perf · refactor · docs · style · test · build · ci · chore · revert
TitleIn the changelogNext version
feat(chat): paste images into the composerFeaturesminor bump
fix(terminal): keep the close button clickableFixespatch bump
perf(timeline): virtualise long sessionsPerformancepatch bump
revert: …Revertspatch bump
refactor, docs, style, test, build, ci, chorenot listedno bump

The commits inside your branch reach main too, and they are read the same way: one written in Conventional form (fix: …) is a changelog entry of its own, next to the title's.

How a release happens

Nobody bumps versions or writes the changelog by hand. A bot, release-please, reads the titles that land on main and keeps one pull request open called chore: release X.Y.Z:

  main ──■──────■──────■──────■──────────────────■───────────────────►
         │      │      │      │                  ▲
       feat:  fix:   fix:   feat:                │ merge the release PR
         │      │      │      │                  │
         ▼      ▼      ▼      ▼                  │
     ┌─────────────────────────────────────────┐ │
     │ PR: chore: release 0.6.0                │─┘
     │  • version → 0.6.0 everywhere           │       tag alpha-0.6.0
     │  • CHANGELOG.md: Features / Fixes       │ ───►  GitHub release
     │  updated on every merge to main         │       installers built and attached
     └─────────────────────────────────────────┘
  1. Every merge to main updates the release pull request: the next version and the changelog.
  2. When you want to ship, review the release pull request and merge it. That is the whole decision, and anyone on the team can make it.
  3. Merging tags alpha-X.Y.Z, publishes the GitHub release with the changelog as its notes, and builds the installers:
  tag alpha-0.6.0
        │
   ┌────┴────────────┬──────────────────┬──────────────────────────────┐
   ▼                 ▼                  ▼                              ▼
 Linux            macOS DMGs         Windows MSI                  after a try-out:
 (verified on     (signed and        (x64)                        tell installed apps
  4 distros)       notarized)                                     an update exists

Linux builds on every release. The macOS and Windows jobs are switched on once their signing secrets and keys are in place; until then those installers are built by hand and attached to the same release.

The last step stays manual on purpose: installed apps are told about a release only after someone has used the build.

Version numbers

Atlas is before 1.0, so a version is 0.MINOR.PATCH:

  0 . 6 . 2
  │   │   └─ PATCH: a release with only fixes          0.6.1 → 0.6.2
  │   └───── MINOR: a release with any new feature     0.6.2 → 0.7.0
  └───────── stays 0 until 1.0

Every release gets a new number. At 1.0 the first number starts meaning "breaking change", as in semver.

Hotfixes

Sometimes a shipped version needs a fix while main already holds work that isn't ready. Then, and only then, a release/X.Y branch is made from that release's tag:

  main ──●──────●──────●──────●(fix)──────●──────►
         │                     │
    alpha-0.6.0                │ cherry-pick: copy just that one commit
         │                     ▼
         └──► release/0.6 ──────●──► tag alpha-0.6.1

The fix lands on main first, as a normal pull request. Then it is copied onto release/0.6 (a cherry-pick copies one commit onto another branch) and tagged alpha-0.6.1. The branch is never merged back, since main already has the fix. The repository's CONTRIBUTING.md has the exact commands.

What lives where

NameWhat it isLives for
mainThe trunk. Always builds, passes CI and could shipforever
<you>/<short-slug>One issue's worth of workdays; deleted on merge
release-please--…The bot's release pull request branchuntil the release
release/X.YHotfixes for a shipped versionas long as needed
alpha-X.Y.Z (tag)A releaseforever

On this page