Skip to content

Workflow

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

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.

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. 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.

Commits

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, or decisions. 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 a BREAKING CHANGE: footer, such as feat(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 dev and main are signed. A contributor's commits don't have to be: they are signed by the maintainer when they land.

The changelog

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.

Decision records

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.

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 pnpm check on the pull request. Run the same thing locally first:

pnpm check

To run it on every commit of the branch, which is what "each commit passes alone" means:

git rebase --exec 'pnpm check' origin/dev

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 not used: 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". 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

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.

Releasing

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-DD and 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 is published from where

What Branch Workflow Now
The wiki, a mirror of docs/ dev .github/workflows/wiki.yml publishing
The website main .github/workflows/pages.yml planned

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.

LibreBars

Clone this wiki locally