Repository navigation
0003 branching and landing
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.
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.
-
devis the default branch and where every change lands. It passes the checks at every commit. -
mainis the last release. It only moves by fast-forward todev, so it is always an ancestor ofdev. -
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, anddevis 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.ymlruns it in a job namedcheckon pull requests intodev. A step is added to the script when the thing it checks exists. -
Branch rules on
devandmain: no force-pushes, no deletion, signed commits, linear history, and thecheckstatus required. A pull request as such is not required, because that rule would reject the fast-forward push. Sincecheckonly runs on pull requests, a commit can still only reachdevthrough one. -
The wiki is published from
devand the website frommain(0005, 0025). -
A release is
mainfast-forwarded todev, with a signed tagvX.Y.Zon that commit (0004).
The commands are in docs/workflow.md.
- Landing a change takes a few commands instead of a button. In return the history is
linear, every commit on
devandmainis signed, and every one has passed the checks. - The maintainer cannot push an unchecked commit to
deveither. 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.
Generated from docs/ on dev. Edit the docs there; changes made on the wiki are overwritten.
- Development
- Workflow
-
Decisions
- 0001 Decisions are recorded
- 0002 Apache License 2.0
- 0003 Changes land on dev by fast-forward; main is the last release
- 0004 Conventional Commits, Keep a Changelog and Semantic Versioning
- 0005 docs/ is for developers and is mirrored to the wiki
- 0006 LibreBars is a free workout log for calisthenics
- 0007 The tracker is an iOS and Android app; its web build stays until the store release
- 0008 LibreBars is an app and a crowd-sourced open database
- 0009 The database is ODbL, media is CC BY-SA, and neither can be closed later
- 0010 A hosted API with a free tier is the paid product
- 0011 The workspace is app, web and api, with engine, ui, data and contracts
- 0012 The engine is small pure functions, in the style of date-fns
- 0013 Web and app share a Tailwind theme, not components
- 0014 Postgres is the source of truth for all data
- 0015 The API is Fastify, and it owns LibreBars accounts
- 0016 Every install is a guest account, made in the background
- 0017 Accounts use Better Auth
- 0018 The on-device database is SQLite with Drizzle, on every platform
- 0019 Sync is our own push and pull
- 0020 The app says it backs up, and backup can be turned off
- 0021 Postgres 18, run with Docker Compose and tested on two databases
- 0022 expo-sqlite is patched so the web build reuses one buffer
- 0023 Seed data is TypeScript modules in packages/data, with permanent ids
- 0024 The first tables
- 0025 One TanStack Start app is the website, on GitHub Pages
- 0026 The catalog reaches the app as a snapshot plus updates, and the website through the API
- 0027 The app's first components are its own