Are there upgrade paths for people who are on 6.x or before?

[anon50000]

I find documentation really lacking on this front, and frankly, it prevents me as a user from being able to get the latest build (because I know that it might result in my spending an inordinate amount of time that I don't have trying to get my setup right). To be clear, I really love the setup that I have right now.

[farfromexact]

For users on 6.x or earlier, I would publish a staged migration path before asking them to try the latest build. The main risk is not the Git pull itself; it is that a newer structure or configuration format can turn a working personal system into a manual reconstruction project.

A safe upgrade guide should include:

1. The exact source version range supported by each upgrade step.
2. A backup/export command that captures both content and configuration.
3. A dry-run or copy-of-the-directory migration.
4. A version-by-version map of renamed or moved files.
5. A verification checklist for the key workflows.
6. A rollback procedure that does not depend on the new version starting successfully.

For a major jump, I would recommend cloning the current setup into a separate directory, running the migration there, and comparing the resulting structure before touching the live 6.x installation. Keep the old directory and tag/commit until the new version has survived a normal work cycle.

If there are several historical formats, a one-shot importer from the oldest supported version is often less confusing than documenting every pairwise upgrade. The guide should also say what is intentionally not migrated, because silent omission is worse than an explicit manual step.

The missing information needed to give a precise command is the exact 6.x release and whether the setup uses the default layout or custom paths. Those two facts determine whether a direct upgrade is safe or whether an intermediate release is needed.

[xmasyx]

We did this jump twelve days ago — a heavily modified 6.0.5 to 7.1.1 — and the checklist above matches what actually mattered. Some numbers from the other side of it, plus the two things that bit us that no checklist predicted.

What we did

The migration itself was by hand, phase by phase, with the old tree kept intact and read-only rather than deleted. That part worked and I would do it the same way again: the old install is still on disk, still readable, and we go back to it for history several times a week. Keeping the predecessor is worth more than the disk it costs — not as a rollback (we never rolled back) but as a reference for "how did this used to work".

What we skipped, and paid for, was measuring the result. For eleven days we assumed the new install was "7.1.1 plus a few tweaks" without ever checking. Last night we finally compared the extracted release tree against the install, file by file, by SHA-256:

	files
identical to the release	1511
differing	21
in the release, absent locally	98
local only	604

Two of those numbers are lies you should expect to see yourself. The 98 "missing" were almost entirely the USER/ template — a directory that is a symlink to personal data here, so the walker never entered it; re-checked against the symlink target it was 86 present, 9 genuinely absent, and 8 of those 9 turned out to be a deliberate format choice (the split per-topic TELOS files, superseded upstream by the unified TELOS.md). Of the 604 "local only", 522 were build output. The raw diff is mostly noise; the signal is the 21.

Anyone can run this today, before upgrading, with no tooling: download the release tarball for the version you are on, hash every file in LifeOS/install/**, compare against your tree. Knowing your delta is a different question from migrating it, and it is the one that is answerable in advance.

The two things that bit us

1. Migration detectors that could not answer their own question. The migration registry ships detectors that report each step as applied or missing. One of them tested for /^LifeOS\/MEMORY\// while the real directory is all-caps LIFEOS — a regex that could never match, so that migration reported itself missing forever, on every install, no matter what the user did. Another reported a security guard as "applied" because it was registered in settings, while the file that arms it with patterns was absent — registered but toothless. Both were green-looking failures.

The general shape: a detector that has never been made to fail is an assertion wearing a lab coat. Before you trust "7 of 7 applied", make one of them go red on purpose.

2. Scheduled jobs survive the version change; their targets do not. launchd agents live outside the repo, in ~/Library/LaunchAgents. After our migration one kept firing daily against a script path that now existed only in the old tree. It failed silently for six days while the dashboard implied a working automation. Worth adding to the checklist above as a seventh item: after migrating, diff every scheduled job's ProgramArguments against what actually exists on disk. Nothing else will tell you.

What we built, and how it answers the six points

Because the delta turned out to be small but load-bearing, we built a registry of it — and it maps onto the checklist above more directly than we expected:

• (4) version-by-version map of moved files → a JSON entry per local difference: what it does in plain language, what breaks without it, which files it touches, and its upstream status.
• (5) verification checklist for key workflows → each entry names a behavioral probe that answers "does this still work?", deliberately independent of who made it work. Not "is my edit still present", which is an assertion about a string. For a fix that makes stray files git-ignored, the probe asks git check-ignore — true whether our rule or an upstream rule does it.
• (3) dry-run migration → a non-mutating planner joins release tree + install + registry and prints, per file: take upstream, keep ours, regenerate, or unclassified. A differing file that no registry entry claims blocks the apply outright. Reconciling an unclassified file means guessing, and the guess that loses is silent — the file goes back to upstream and the reason it was different goes with it.
• (6) rollback that does not depend on the new version starting → the registry carries re-apply instructions per entry, in text, readable without running anything.
• (2) backup capturing content and configuration → worth splitting by channel and being explicit about which covers what. Ours: the system repo covers code and docs; the personal layer is a symlink to a separate repo; memory is gitignored entirely and depends on machine backups. "I committed" and "it is safe" were not the same sentence, and we did not notice until we drew the map.
• (1) supported source version range → the one we cannot answer for you, and the one the maintainers would have to state.

The verdict we care about most is the fourth one: a fix that works without our change too, because upstream has since fixed the underlying defect. That does not retire anything automatically — it emits a comparison and a human decides. We have a patch whose upstream issue reads CLOSED while the fix never landed in the upstream file, so anything that drops local changes on issue status will delete live guards. An issue state is an opinion; a defect that will not reproduce is a fact; and two working solutions still do not choose between themselves.

And the problem we caused ourselves

Building that verifier, we wrote a fork bomb. The upgrade check spawns the verifier; a probe in the verifier spawned the upgrade check to measure whether it mutated anything. Neither had a recursion guard, because each was written believing it was the one doing the verifying. Roughly 700 processes in four minutes, every one of them fetching from the network, and it drained the unauthenticated GitHub API bucket (60/hour per IP) so that the tool then answered 403 to itself for an hour. It was caught because the bandwidth was noticed — nothing reported an error, since every individual process was behaving exactly as designed.

Two transferable lessons: the guard belongs in the child's environment at the spawn site, never exported into the process (an exported value outlives the command and silently disables the probe in legitimate runs); and "cannot answer from here" deserves a different verdict from "tried and failed", printed rather than skipped silently. The negative pole for a fork bomb is pleasingly simple, too: the command has to terminate.

Full write-up of the mechanism is in #1613 if it is useful. None of it is a substitute for the staged path and the version map you are asking for — those have to come from the project. But the part a user can own is knowing exactly what their own delta is, and having something that goes red when an upgrade takes a piece of it away, instead of finding out weeks later when the bug you fixed in March comes back looking new.

[danielmiessler]

This should be significantly improved in the last two releases, and especially the latest one.