Releasing Popfold, and updating a site
Popfold and the sites built on it are separate repositories. A site holds Popfold as a git submodule in
popfold/, pinned to a release tag, and moves to a newer release only when someone moves it. So a change to
Popfold reaches a site in two steps: release Popfold, then update the site.
Alpha. Any release may break a site. That is allowed before 1.0.0, and it is why sites pin a tag.
There are two ways to change Popfold. Use the first when the change comes out of work on a site, which is most of the time. Use the second for work on Popfold alone (its docs, the template, the model tools).
Change the engine while working on a site
Every site has its own working copy of Popfold in popfold/. Change the engine there: the site's dev server
shows the change at once, and several people or agents can each change the engine from their own site without
touching each other's files. Git brings the changes together.
-
Start a branch in the site's copy, from the newest
main:git -C popfold fetch origingit -C popfold switch -c <site>/<topic> origin/main # e.g. consulting/wall-hingesStarting from
main, not from the tag the site pins, means the site also takes whatever was merged since its pin. Readpopfold/CHANGELOG.mdif the site then needs a change. -
Edit files under
popfold/. Keep the change general: nothing that belongs to this one site goes into Popfold (no site name, person's name, brand colour, section id or CSS class). If only this site needs it, it belongs in the site, perhaps behind a new option of the engine. -
Prove it in the site:
pnpm typecheck,pnpm build, andpnpm exec popfold stills --checkto see exactly which stills the change alters. -
Record it: a line under
## Unreleasedinpopfold/CHANGELOG.md(say what a site has to do, if anything), and the docs page that describes what you changed. -
Commit inside
popfold/, naming the files:git -C popfold add <files> && git -C popfold commit. -
Push the branch and open a pull request on the Popfold repository, when the owner says so:
git -C popfold push -u origin <site>/<topic>gh pr create --repo <owner>/popfold --head <site>/<topic> --base mainPopfold's CI typechecks it and builds the template. Merge when it is green and the owner agrees.
-
Release it (next section), then pin the release in the site:
pnpm exec popfold update v<version>, and commit the site.
While the change is not released yet, the site may commit its popfold/ pointer at the branch's commit to keep
working, as long as that commit is pushed (the site's CI fetches it by its id). Move the site to the release
before the work is called done: a site should rest on a tag.
Two sessions changing the same engine file from two sites will meet in the pull requests. The second one
rebases onto the new main (git -C popfold fetch origin && git -C popfold rebase origin/main) and checks its
site again.
Change Popfold on its own
Work in a clone of the Popfold repository that is not inside a site.
- Make the change. Add a line under
## UnreleasedinCHANGELOG.mdsaying what changed and, if it breaks sites, what a site has to do. pnpm -r typecheckandpnpm -r build.- If the change can alter how a home looks, try it in a site before releasing: in a clone of the site, point the
submodule at your working copy (
git -C popfold fetch <path to your Popfold> <branch> && git -C popfold checkout FETCH_HEAD), build, and runpnpm exec popfold stills --check. It lists the stills that differ and by how much. - Commit. Push when the owner says so.
Cut a release
pnpm release 0.2.0
Cut releases in a clone of Popfold that is not inside a site (a site's popfold/ shares the site's workspace),
one at a time: pull first.
This runs tools/release.mjs. It refuses to start unless the tree is clean, you are on main and not behind
origin/main, the version is newer, and CHANGELOG.md has notes under ## Unreleased. Then it:
- moves those notes under
## 0.2.0 (alpha), <today>and leaves an empty## Unreleasedabove them; - sets the version in
package.json, every template and the README; - installs, typechecks and builds everything;
- commits
Popfold 0.2.0 (alpha)and makes the tagv0.2.0.
Nothing is pushed. When the owner says so:
git push origin main
git push origin v0.2.0
Version numbers before 1.0.0: raise the middle number when sites have to change something, the last number when they do not.
Update a site
In the site's folder:
pnpm exec popfold update # to the newest release
pnpm exec popfold update v0.2.0 # or to a named one
It fetches Popfold's tags, lists the commits the site is about to take, moves popfold/ to the tag, then runs
pnpm install, pnpm typecheck and pnpm build. If the site no longer builds, it says so and tells you how to
go back. It commits nothing and captures no stills, so it does not use the GPU.
Then finish by hand:
- Read
popfold/CHANGELOG.mdfor anything the site has to change, and change it. pnpm build:staticrecaptures the stills (this uses the GPU) and lists the ones that changed. Stills that look the same are left untouched. Look at each changed one.- Commit the move:
git add popfold pnpm-lock.yaml public/stills && git commit -m "Popfold v0.2.0". - Push when the owner says so, and check the site's CI.
Releases up to 0.1.0 have no update command. From one of those, move by hand once:
git -C popfold fetch --tags origin && git -C popfold checkout v0.2.0
pnpm install && pnpm typecheck && pnpm build
A site's CI and private Popfold
A site's own token cannot read a private Popfold repository. Its CI fetches the pinned commit with a read-only
deploy key that lives on the Popfold repository; the private half is the site's secret POPFOLD_DEPLOY_KEY.
A new site needs that secret: make a new key pair for it, add the public half to Popfold as a read-only deploy
key, and store the private half in the site. The organisation must allow deploy keys.