Repository navigation
feat(stack): run stacklet migrations once, in order, on stack up - #231
Merged
Merged
Conversation
arthware-dev
force-pushed
the
feature/0.5.0-beta.1
branch
from
October 16, 2026 12:36
8b3033a to
2d08a31
Compare
arthware-dev
force-pushed
the
feat/stacklet-migrations
branch
from
October 16, 2026 12:56
aad3d08 to
95e32c9
Compare
arthware-dev
force-pushed
the
feature/0.5.0-beta.1
branch
from
October 16, 2026 15:07
2d08a31 to
489222f
Compare
added 3 commits
October 16, 2026 17:07
A stacklet that changes data it already wrote had nowhere to put the change, so each one invented its own trigger and its own record. Now a stacklet ships `migrations/NNNN_<name>.py` with `def run(ctx)`, and `stack up` runs the pending ones after `on_start_ready`, once every health check passed, in number order. - The record lives with the data: `<data_dir>/<id>/.migrations.json`. A migration that commits to a repository on the code host declares `REPO`, ends its commit message with `ctx.trailer` (`Migration: <id>/<NNNN>`) and returns the sha; it counts as applied while that commit is in the repository, and runs again once a restore has taken it away. - The first failure stops the run, is printed and recorded, and `stack up` exits 1 with the containers left running. The rest wait; the next `stack up` retries it. - Commands that start several stacklets start all of them first, then migrate in dependency order. Bare `stack restart` goes the same way. - `stack doctor` lists pending, failed, and data migrated by a newer release. `stack update` names the migrations a release brings and, before moving to a release that lacks one applied here, says so. - `stack.bot_runner.call` runs a bot-runner command and raises on failure, for migrations whose work needs a bot's code. The contract is in `docs/stack-reference.md` under Migrations, which also corrects the runtime state directory to `.stack/`. Refs: #220
`stack up memory` read every topic's `todos.md` on every start to move it to `lists/`, and a failure was only a warning. The move is now migration memory/0001: it runs once per instance, its commit carries `Migration: memory/0001`, and a commit Forgejo refuses (a list edited meanwhile) fails `stack up memory` and is retried on the next one. Refs: #220
The archivist moved the photos filed as bookmarks to notes a minute after it started, left a marker file in its data dir, and logged a failure inside the bot runner where nobody saw it. The move is now migration docs/0001, run by `stack up docs` through a new bot-runner command, `migrate-photos-to-notes`, which downloads an old entry's upload with the archivist's own Matrix session. Its commit carries `Migration: docs/0001`, a failure fails `stack up docs`, and the old marker file is removed. An instance that already moved its photos runs it once more and finds nothing to move. Refs: #220
arthware-dev
force-pushed
the
feat/stacklet-migrations
branch
from
October 16, 2026 15:07
95e32c9 to
851c0a6
Compare
arthware-dev
added a commit
that referenced
this pull request
Oct 17, 2026
## Summary - A stacklet ships data migrations as `migrations/NNNN_<name>.py`. `stack up` runs the pending ones once, in order, after a healthy start; the first failure stops the run and exits 1 with the containers up. `stack doctor` lists pending, failed and newer-than-checkout migrations; `stack update` names arriving ones and warns before moving to a release that lacks an applied one. - The record lives with the data in `<data_dir>/<id>/.migrations.json`. A family memory migration also ends its commit with `Migration: <id>/<NNNN>` and returns the sha; it counts as applied while that commit is in the repository and runs again when it is gone. - The to-do move (memory/0001) and the photo move (docs/0001, now a bot-runner command) run through it. Merge mode: rebase. The three commits stand alone and each passes commit-lint. Closes: #220
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
migrations/NNNN_<name>.py.stack upruns the pending ones once, in order, after a healthy start; the first failure stops the run and exits 1 with the containers up.stack doctorlists pending, failed and newer-than-checkout migrations;stack updatenames arriving ones and warns before moving to a release that lacks an applied one.<data_dir>/<id>/.migrations.json. A family memory migration also ends its commit withMigration: <id>/<NNNN>and returns the sha; it counts as applied while that commit is in the repository and runs again when it is gone.Merge mode: rebase. The three commits stand alone and each passes commit-lint.
Closes: #220