Repository navigation
0012 branching and release workflow
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.
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.
-
devis the default branch and where every change lands. It is expected to pass the checks at every commit. -
mainis the last release. It only ever moves by fast-forward todev, so it is always an ancestor ofdevand 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, anddevis 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.ymlruns one job,check, on pull requests intodev: lint, typecheck, tests, the website build and the docs link check. -
Branch rules on
devandmain: no force-pushes, no deletion, signed commits, linear history, and thecheckstatus required. Approvals are not required, and neither is a pull request as such: a rule requiring one would reject the fast-forward push. Becausecheckonly runs on pull requests, a commit can still only reachdevthrough 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
mainfast-forwarded todev. 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.
- 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 or to anything else published from
mainis not live until the next release. A change to the docs is on the wiki as soon as it lands ondev. - Links from the wiki into the repository point at
dev; links from the website point atmain. - 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.
Generated from docs/ on dev. Edit the docs there; changes made on the wiki are overwritten.
- The open database and the API
- Development
- Parity with StrongLifts
- Workflow
-
Decisions
- 0001 Decisions are recorded as ADRs
- 0002 Apache License 2.0
- 0003 Parity with StrongLifts, everything free
- 0004 iOS, Android and web
- 0005 Local-first; accounts and sync later through Spotcraft
- 0006 openweight for import and export, not for storage
- 0007 One Expo app, wrapped in Electron for desktop
- 0008 A pnpm workspace with app, desktop and core
- 0009 The website is static Astro in apps/website
- 0010 The website is hosted on GitHub Pages at librelifts.app
- 0011 docs/ is for developers and is mirrored to the wiki
- 0012 Changes land on dev by fast-forward; main is the last release
- 0013 LibreLifts is an app and a crowd-sourced open database
- 0014 The database is ODbL, media is CC BY-SA, and neither can be closed later
- 0015 Data contributions start as pull requests; a web editor comes later
- 0016 A hosted API with a free tier is the paid product