Skip to content

0012 branching and release workflow

github-actions[bot] edited this page Nov 17, 2026 · 1 revision

Changes land on dev by fast-forward; main is the last release

Status: accepted · Implementation: done · Date: 2026-11-17

Changes where the wiki is published from (ADR 0011): dev, not main. Versioning, changelogs and release automation are left for a later record.

Context

Until now everything was committed straight to main, and a push to main published both the website and the wiki. That stops working once the app has releases: work in progress and what users have installed need different branches. dev was created and made the default branch, and the rest of the process had to be decided around it.

The project has one maintainer and may get an occasional contributor. Commits are signed and follow Conventional Commits, and a change is a sequence of commits that each make sense alone. Nothing ran the tests or the linter before a change was pushed.

Two of GitHub's three merge buttons work against that. "Rebase and merge" re-creates the commits without their signatures. "Create a merge commit" keeps them but makes the history non-linear. "Squash and merge" produces one commit signed by GitHub, which is linear but collapses the sequence.

Decision

  • dev is the default branch and where every change lands. It is expected to pass the checks at every commit.
  • main is the last release. It only ever moves by fast-forward to dev, so it is always an ancestor of dev and the two never diverge.
  • Every change goes through a topic branch and a pull request into dev, the maintainer's included. Topic branches are named <type>/<name> after the Conventional Commits type of the change.
  • A pull request lands as a fast-forward push: the branch is rebased onto dev, the checks run on those exact commits, and dev is pushed forward to them. GitHub then shows the pull request as merged. The commits keep the maintainer's signatures and their sequence.
  • A contributor's pull request is rebased and signed by the maintainer, who becomes the committer while the contributor stays the author, and lands the same way. "Squash and merge" is the fallback. Merge commits and GitHub's rebase are turned off.
  • .github/workflows/ci.yml runs one job, check, on pull requests into dev: lint, typecheck, tests, the website build and the docs link check.
  • Branch rules on dev and main: no force-pushes, no deletion, signed commits, linear history, and the check status required. Approvals are not required, and neither is a pull request as such: a rule requiring one would reject the fast-forward push. Because check only runs on pull requests, a commit can still only reach dev through one.
  • The website is published from main (ADR 0010, unchanged): it is for people who use the app, so it follows releases.
  • The wiki is published from dev, which changes ADR 0011: the docs are for people who work on the project, so they follow the branch the work is on.
  • A release is main fast-forwarded to dev. From the first release of the app it is also a signed tag, vX.Y.Z, on that commit.

The commands are in docs/workflow.md.

Consequences

  • Landing a change takes a few commands instead of a button. In return the history is linear, every commit on dev and main is signed, and every one has passed the checks.
  • The maintainer cannot push an unchecked commit to dev either. A one-line fix still needs a branch and a pull request.
  • A change to the website or to anything else published from main is not live until the next release. A change to the docs is on the wiki as soon as it lands on dev.
  • Links from the wiki into the repository point at dev; links from the website point at main.
  • A pull request landed with "Squash and merge" is signed by GitHub, not by the maintainer.
  • How versions are numbered between releases, whether there is a changelog, and how the app and desktop builds are produced for a release are not decided here.

Clone this wiki locally