Skip to content

Workflow

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

Workflow

How a change gets from an idea to dev, and from dev to a release. The reasons are in ADR 0012. If you are contributing from a fork, CONTRIBUTING.md is the short version.

Branches

Branch What it is How it moves
dev The default branch. Everything lands here first, and it stays green. Fast-forwarded to a checked pull request.
main The last release. The website is published from it. Fast-forwarded to dev.
<type>/<name> A topic branch for one change, such as feat/rest-timer or fix/plate-rounding. Rebased on dev; deleted once landed.

The type in a branch name is the Conventional Commits type of the change: feat, fix, docs, chore, ci, refactor, test.

History on dev and main is linear, and main is always an ancestor of dev. Neither branch accepts a force-push, an unsigned commit, or a commit that hasn't passed the checks.

Commits

  • Messages follow Conventional Commits.
  • A change is a sequence of commits that each make sense alone, not one large commit.
  • Commits on dev and main are signed. A contributor's commits don't have to be: they are signed by the maintainer when they land (see below).

Landing a change

Every change goes through a pull request into dev, the maintainer's own included. The pull request is where the checks run.

git switch -c feat/rest-timer origin/dev
# ...commit...
git push -u origin feat/rest-timer
gh pr create --base dev

The check job in .github/workflows/ci.yml runs on the pull request: lint, typecheck, tests, the website build and the docs link check. To run the same things locally:

pnpm lint && pnpm typecheck && pnpm test && pnpm website build && pnpm wiki

When the change is ready, it lands as a fast-forward, so dev gets exactly the commits that were checked, with their signatures:

git fetch origin
git rebase origin/dev              # only needed if dev has moved
git push --force-with-lease        # only needed if you rebased
gh pr checks --watch               # wait for "check" on the final commits
git push origin HEAD:dev           # fast-forward dev
git push origin --delete feat/rest-timer

GitHub marks the pull request as merged when its commits appear on dev. The merge buttons for merge commits and for rebasing are turned off: a merge commit breaks the linear history, and GitHub's rebase re-creates the commits without their signatures.

Landing a contributor's pull request

A pull request from a fork lands the same way, with the maintainer doing the last steps:

gh pr checkout 123
git rebase -S origin/dev           # the author stays the author; the maintainer signs
git push --force-with-lease        # back to the contributor's branch
gh pr checks 123 --watch
git push origin HEAD:dev

Pushing back to the contributor's branch needs "Allow edits from maintainers", which is on by default for a pull request from a fork. If that isn't possible, or the commits aren't worth keeping apart, use Squash and merge on GitHub instead: one commit, signed by GitHub, and the history stays linear.

Releasing

A release moves main forward to dev:

git fetch origin
git push origin origin/dev:main    # fast-forward only; never forced

That publishes the website if anything it is built from has changed (.github/workflows/pages.yml).

Nothing has a version number yet. From the first release of the app, a release is also a signed tag on the commit main points at:

git tag -s v1.0.0 -m "v1.0.0" origin/main
git push origin v1.0.0

What is published from where

What Branch Workflow
The website, librelifts.app main .github/workflows/pages.yml
The wiki, a mirror of docs/ dev .github/workflows/wiki.yml

The website is for people who use the app, so it follows releases. The docs are for people who work on it, so they follow dev.

Clone this wiki locally