Skip to content

0003 branching and landing

github-actions[bot] edited this page Nov 18, 2026 · 2 revisions

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

Status: accepted · Implementation: planned · Date: 2026-11-18

From LibreLifts ADR 0012. The check is one script, pnpm check, which LibreLifts kept as a command written out in three places. As built, 2026-11-18: pnpm check, the check job and docs/workflow.md exist. The branch rules and the merge-button settings are not set on GitHub yet, so this stays planned. main was moved to dev for the first time on 2026-11-18, by fast-forward, with no version and no tag.

Context

One person maintains LibreBars 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, and pass the checks, alone.

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" gives one commit signed by GitHub, which is linear but collapses the sequence.

Decision

  • dev is the default branch and where every change lands. It passes the checks at every commit.
  • main is the last release. It only moves by fast-forward to dev, so it is always an ancestor of dev.
  • 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 (git push origin HEAD:dev). GitHub then shows the pull request as merged.
  • A contributor's pull request is rebased and signed by the maintainer, who becomes the committer while the contributor stays the author. "Squash and merge" is the fallback. Merge commits and GitHub's rebase are turned off.
  • One command checks everything: pnpm check. .github/workflows/ci.yml runs it in a job named check on pull requests into dev. A step is added to the script when the thing it checks exists.
  • Branch rules on dev and main: no force-pushes, no deletion, signed commits, linear history, and the check status required. A pull request as such is not required, because that rule would reject the fast-forward push. Since check only runs on pull requests, a commit can still only reach dev through one.
  • The wiki is published from dev and the website from main (0005, 0025).
  • A release is main fast-forwarded to dev, with a signed tag vX.Y.Z on that commit (0004).

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 is not live until the next release. A change to the docs is on the wiki as soon as it lands on dev.
  • A pull request landed with "Squash and merge" is signed by GitHub, not by the maintainer.

LibreBars

Clone this wiki locally