halkyon/docs/adr/0015-one-repository.md

ADR 0015: One repository for every app and the packages they share

• Status: accepted
• Date: 2026-10-19
• Decided by: the developer, after Melos in each repository was offered instead.

Context

Until 19 Oct 2026 Halkyon lived in three repositories: Learn's (halkyon_learn), the shared packages' (halkyon_shared: halkyon_ui, the halkyon_base module of ADR 0014, halkyon_app, halkyon_core, halkyon_interop) and Todo's, a local scaffold. Learn took the shared packages by git, pinned to signed commits of halkyon_shared's main, as it pins the offline sync fork. Every change to a shared package was a round trip: commit there, the developer signs and pushes, sends the hash, Learn's pins move, Learn's checks run again. On 18 and 19 Oct alone that took four rounds (the theme and widgets, the module, halkyon_app, data locations as precise as a state), each change only complete across two repositories. Todo, Train and Meditate are expected to grow like Learn, slightly smaller, on the same shared packages, so the rounds would multiply. Asked whether Melos, which runs scripts across a workspace's packages, was worth setting up, the developer chose one repository for everything, with Melos on top.

Decision

1. One repository, project-halkyon/halkyon on code.halkyon.app: Learn's renamed. It keeps the CI runner's registration, the Actions, the tags and the releases, and Forgejo redirects the old address, so the server's checkout and the F-Droid listing keep working until they are pointed at the new one.
2. The layout: apps/<app>/ with each app's packages (apps/learn/: server, client, app, curator, and tool/ with the scripts writing Learn's assets; apps/todo/), packages/ with the shared packages, deploy/ at the root as the instance deploy (other services' compose files are to join Learn's there, which settles how an operator adds a second service), snap/ at the root (Learn's snap needs the whole workspace to build), tool/ with the repository's tools, docs/adr/ with one numbering for every app.
3. One pub workspace: the root pubspec.yaml lists every package; one pubspec.lock holds one version of each dependency for every app; the apps take the shared packages by path; the root's dependency_overrides hold for every app (the sync fork; cli_util, below). Todo moved to Serverpod 4.0.4 and Dart 3.13 with the rest.
4. History kept, nothing rewritten. Learn's history is the repository's. halkyon_shared's is merged in as it was, its packages read into packages/ by the merge itself, so its four commits keep their signatures. Todo's scaffold came in as files: its one commit held the scaffold alone and was unsigned, and the deploy refuses every commit new to it that isn't signed by a key in deploy/allowed-signers. Learn moved into apps/learn/ by a commit of renames alone, so git log --follow and blame follow every file.
5. Signing takes one rebase that re-signs only what isn't signed yet: git rebase -r --exec '[ "$(git log -1 --format=%G?)" = G ] || git commit --amend --no-edit -S' main. A merged commit whose parents don't change is kept as it is, signature and all; tested in a scratch repository before the move.
6. Melos 8.9, a dev dependency of the root (dart run melos …), runs scripts across the packages (analyze, test:dart, test:flutter, generate, check), each taking Melos' filters (--diff, --include-dependents, --scope).
7. Tools in Dart where they hold logic, Bash for glue and for the production host, Python only for Python-only libraries. tool/check.dart replaces tool/check.sh (its file selection tested in the root's test/), with --changed-since=<commit> for only what changed and what depends on it; tool/pre-push is the hook (the signature check, then the checks). deploy/redeploy.sh and deploy/backup.sh stay Bash: the production host has no Dart SDK and gets none. Learn's tool/release.sh stays Bash until build 21 is out, so the release that goes with ADR 0014's breaking deploy uses the script it was proven with; then a release tool in Dart, shared by the apps and tagging per app (learn-vX.Y.Z), takes over.
8. The move happens while deploys pause (until 22 Oct, after the hackathon's judging): the first deploy from the new layout comes with build 21.

Consequences

• A change to a shared package and to every app using it is one commit, checked as one; a shared package's change must keep every app's tests passing in the same commit.
• One version of each dependency across the apps: an app's upgrade moves every app. Serverpod moves as one already (ADR 0014). Melos needs cli_util 0.5, which Learn's flutter_launcher_icons (0.14.4, its latest) doesn't allow; the root overrides it to 0.5.2, as that package uses only cli_util's logger, unchanged in 0.5. Drop the override once it allows 0.5.
• CI checks every package on every push, and the generated-code check covers every server package (dart run melos run generate); the four throwaway test passwords CI gives cover the module's and Todo's server tests too.
• Deploys: deploy/ stays at the root, so the command the runner's key is pinned to on learn.halkyon.eu's server (/home/deploy/halkyon-learn/deploy/redeploy.sh) is unchanged, and the server's checkout keeps its folder. Its images are built from the root with the workspace narrowed to what they need (tool/workspace_only.sh: Learn's server and the module; the curator), checked by building both images before the move. The first deploy after the move starts the server once more than needed, as the deployed copy of redeploy.sh looks for migrations at their old path.
• halkyon_shared's repository is archived, not deleted: Learn's commits before the move pin it. Its commit style gives way to the repository's typed commits.
• Todo's packages have no licence until the developer decides (LICENSE.md).
• References to the old repository address in code and listings (the source link Learn's instances name, the snap's and the F-Droid listing's source, the curator's credits) work through Forgejo's redirect until they are changed to project-halkyon/halkyon.