Repository navigation
Workflow
How a change gets from an idea to dev, and from dev to a release. The reasons are in
0003 and
0004. If you are contributing from a fork,
CONTRIBUTING.md is the short version.
| 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. | Fast-forwarded to dev. |
<type>/<name> |
A topic branch for one change, such as feat/rest-timer. |
Rebased on dev; deleted once landed. |
The type in a branch name is the Conventional Commits type of the change.
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.
Messages follow Conventional Commits 1.0.0:
<type>(<scope>): <description>
-
Types:
feat,fix,docs,chore,ci,refactor,test. -
Scopes:
app,api,web,engine,ui,data,contracts, ordecisions. Leave the scope out when the commit is about the repository as a whole. -
The description is lowercase, in the imperative, with no full stop:
add rest timer. -
A breaking change has
!after the type or scope and aBREAKING CHANGE:footer, such asfeat(app)!: drop support for iOS 17. - A change is a sequence of commits that each make sense, and pass
pnpm check, alone. - Inside a pull request the order is: decision records, then code, then docs.
- Commits on
devandmainare signed. A contributor's commits don't have to be: they are signed by the maintainer when they land.
CHANGELOG.md follows Keep a Changelog 1.1.0
and is written by hand for the people who use LibreBars. A commit that changes something
they would notice adds a line under [Unreleased], in one of its groups: Added, Changed,
Deprecated, Removed, Fixed or Security. A refactor, a CI change or a change to these docs
does not.
A pull request that makes or changes a decision starts with a docs(decisions): commit that
adds the record, before the code that acts on it. Its last docs: commit sets
implementation: done on the records it built, adds a note where the build differed from the
record, and updates the index. The format is in
0001.
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 devThe check job in .github/workflows/ci.yml runs pnpm check on the pull request, and a
second job, api-postgres, runs the API's tests again on a real Postgres. Run the check
locally first:
pnpm checkTo run it on every commit of the branch, which is what "each commit passes alone" means:
git rebase --exec 'pnpm check' origin/devWhen 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-timerGitHub marks the pull request as merged when its commits appear on dev. The merge buttons
for merge commits and for rebasing are not used: a merge commit breaks the linear history,
and GitHub's rebase re-creates the commits without their signatures.
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:devPushing back to the contributor's branch needs "Allow edits from maintainers". 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.
Versions follow Semantic Versioning 2.0.0. The repository has one
version, in every package.json, and it is 0.0.0 until the first release.
The version of a release is chosen from the commits since the last one:
| Since the last release there is | While 0.y.z
|
From 1.0.0 on |
|---|---|---|
| a breaking change | raise the minor | raise the major |
a feat, and nothing breaking |
raise the minor | raise the minor |
only fix and the rest |
raise the patch | raise the patch |
1.0.0 is the first release of the app in the stores.
Nothing has been released yet. A release is a pull request with one commit,
chore(release): X.Y.Z, that:
- renames
[Unreleased]in the changelog to[X.Y.Z] - YYYY-MM-DDand opens a new, empty[Unreleased]above it; - updates the links at the foot of the changelog;
- sets the version in every
package.json.
Once it has landed on dev, main is moved to it and tagged:
git fetch origin
git push origin origin/dev:main # fast-forward only; never forced
git tag -s vX.Y.Z -m "vX.Y.Z" origin/main
git push origin vX.Y.Z| What | Branch | Workflow | Now |
|---|---|---|---|
The wiki, a mirror of docs/
|
dev |
.github/workflows/wiki.yml |
publishing |
| The website, librebars.app | main |
.github/workflows/pages.yml |
publishing |
The docs are for people who work on LibreBars, so they follow dev. The website is for
people who use it, so it follows releases.
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