product:upgrade
Table of contents
Introduction
product:upgrade moves the product’s features to their newest versions and keeps only the upgrades the running product is seen to pass with. Every upgrade is installed in the product’s container, the database is migrated, the product is validated and its tests run. An upgrade that breaks any of that is told apart from the others and left out.
splent product:upgrade
product:upgrade uvlhub
Feature Pinned Planned
admin v1.10.2 v1.10.3 upgrade
reports v0.5.0 v0.6.1 upgrade
accounts v1.28.0 v1.28.1 upgrade
Upgrade 3 features, proving each on the running product? [y/N]: y
Validating the planned product
the whole plan validates
Proving on the running product
logs in /workspace/.splent_cache/upgrade/uvlhub/20261116-171502
database copied ok
the product as it is
validate ok
migrations at head ok
tests ok
trying admin v1.10.3, reports v0.6.1, accounts v1.28.1
database restored ok
links ok
install and migrate ok
validate ok
migrations at head ok
tests failed, comparing with the product as it was
...
new since the product as it was:
test splent_io/splent_feature_reports/tests/unit/test_menu_entries.py::test_label
in halves, each after the features it requires; suspects last: reports
trying accounts v1.28.1, admin v1.10.3
...
tests ok
the pages, once, with what passed the tests
looking at the pages with accounts v1.28.1, admin v1.10.3
look of the pages ok
Result
admin v1.10.2 v1.10.3 upgraded
reports v0.5.0 v0.5.0 kept: tests failed with v0.6.1
accounts v1.28.0 v1.28.1 upgraded
It works on the active product, which must be running, as product:derive --dev leaves it.
How it proves an upgrade
- The plan. The same as
feature:upgrademakes it: the newest versions that install together, that the contracts accept and that keep every migration history. The planned product goes throughproduct:validatefirst, and an upgrade that does not validate is left out before anything runs. - The product as it is. It must pass
product:validateanddb:status --check. Itsproduct:testruns only when an upgrade fails some test, to tell what the upgrade adds: a plan that passes never needs it. See Judged against the product as it was. - The whole plan. The new versions are pinned, the database is brought back to the copy taken at the start, and
product:restart --fullinstalls them in the container and migrates. Thenproduct:validate,db:status --checkandproduct:test --no-ui-auditrun. When they pass, and the tests fail on nothing new, that is the set that passed the tests. - In halves. Otherwise as many upgrades are kept as pass together. A group is tried on top of what was kept already; when it passes it is kept whole, when it fails it is split in halves, until each upgrade that fails is alone. One upgrade that breaks the product among twenty costs about ten tries, not twenty. Every try starts from the product’s files and database as they were.
The groups follow the dependency order of the contracts, so a feature is tried after the features it requires. Within that order the suspects go last: the upgrades of the features whose own tests failed with the whole plan, and of the features that require them. The groups without them then pass whole.
- The look of the pages, once. A product that declares
[tool.splent.ui_audit]hasproduct:ui-auditrun on the set that passed the tests, and on nothing else: it is the slowest check, every page at every width in a real browser, and an upgrade rarely changes how a page looks. When it finds nothing new, that is the result. When it finds something, the pages of the product as it was are audited to compare with, and only if the set adds something are the upgrades told apart by it, in halves, the same way.
No set of upgrades is tried twice. The last upgrade of a plan that failed whole, once all the others passed, is known to be the culprit without trying it again.
The product ends running the upgrades that passed. When the last set tried failed, the ones that passed are installed again, without running their tests a second time. When none passed, the product is back at the versions it had. The last line says how many sets were tried.
Judged against the product as it was
A product often has failures of its own before any upgrade: a test that depends on the language, a page the UI audit finds too wide on a phone. They should not hold back every upgrade, and an upgrade should not hide behind them. So the run of product:test on the product as it is says what it fails on, by name.
| Kept from the first run | Named by |
|---|---|
| A test that failed | Its pytest node id, as in splent_io/splent_feature_reports/tests/unit/test_menu_entries.py::test_label |
| A UI audit finding | Its page, its kind and its element, as in /team, beyond, a.member-card__email. The theme and width it showed at are left out, so a finding seen at one more width is not a new one |
tests failed, comparing with the product as it was
the product as it was, to compare with
database restored ok
links ok
install and migrate ok
tests fails on 1 test(s) and 5 audit finding(s)
test splent_io/splent_feature_reports/tests/unit/test_menu_entries.py::test_the_label_names_the_month_of_the_report
audit /cite-us: contrast button.btn.btn-outline-primary.active #ffffff on #107eff 3.85:1
...
An upgrade passes when it adds nothing to these.
That run happens the first time an upgrade fails some test, never before: the product as it was is installed again for it, and the attempt that failed is judged against it without running again. From then on, product:test passes for an upgrade when everything it fails on was already there, and the line says so: tests fail on nothing new. When it fails on something new, the new failures are listed and the upgrade is left out.
A failure that names neither a test nor an audit finding, such as a run that could not start, cannot be compared. On the product as it is it stops the command, which changes nothing; with an upgrade, the upgrade is left out.
A page the UI audit could not measure, a browser that timed out on it, is no finding about the page. When the audit of the upgrades leaves pages unmeasured, it runs once more before anything is held against them. A page still unmeasured that the product as it was had measured leaves the upgrades out, as could not be measured, and is never kept for a later run, which tries them again.
--strict asks for a product whose tests pass before any upgrade, and stops otherwise.
What is brought back
Before the first change the database is copied with db:dump, and the product’s pyproject.toml and splent.manifest.json are kept. Every attempt starts from both, and the feature links follow the pins through product:resolve. If the command is interrupted or a step it cannot recover from fails, it brings the product back to how it was. If even that fails, it says where the database copy is.
Ctrl-C and SIGTERM always stop it, whoever started it. The step running then ends together with everything it started, the tests in the product’s container included, and bringing the product back is not cut short by a second signal. A step that a signal ended from outside, with an exit code of a killed process, stops the command the same way: it says nothing about the upgrade, so it is never counted as a failed test. Stopped before anything changed, the command says so and reinstalls nothing.
What an earlier run found
A run keeps two things, for the product exactly as it is, in .splent_cache/upgrade/<product>/memory.json:
- An upgrade that failed alone, or on top of exactly the upgrades the run kept. A later run on the same product does not try it again: it lists it, with when it failed and the log, and reports it as kept.
- What the UI audit found on the pages. A later run that needs the pages of the product as it was compares with those, instead of auditing them again. The audit takes minutes and runs twice when something is found, so this saves the longer half.
“Exactly as it is” is a fingerprint of everything the tests and the audit can see: the product’s pyproject.toml, its src/, tests/ and docker/, the working copy of every feature it declares without a version, and the code of the framework and the CLI. A pinned release never changes, so its name and version say all there is. When any of that changes, nothing kept is used, and a newer release of a feature that failed is tried as usual. --fresh forgets it all and tries everything again.
Where the output goes
Each step is a splent command, run with its output in a log of its own under .splent_cache/upgrade/<product>/<time>/, the command on its first line. A failed step prints its last lines and the path of its log.
Reference
| Argument / Option | Description |
|---|---|
FEATURE |
Optional, one or more. Upgrade only these |
--dry-run |
Print the plan and change nothing |
--yes |
Skip the confirmation prompt |
--pypi-only |
Take only versions PyPI serves |
--no-tests |
Prove with validation and migrations only, without product:test or the UI audit |
--no-baseline |
Do not check the product as it is first, so every failure counts against the upgrades |
--strict |
Ask for a product whose tests pass before any upgrade, instead of judging the upgrades on what they add |
--fresh |
Forget what earlier runs found: try again the upgrades that failed, and audit the pages of the product as it is |
It exits 1 when an upgrade was left out, or not tried because it failed before on the product as it is, the plan refused one, or the product as it is could not be proven: its validation or migrations fail, its tests fail on something unnamed, or they fail under --strict. It exits 130 when interrupted, after bringing the product back.
See also
feature:upgradeplans and pins the upgrades, and validates them without running the product.workspace:statusshows which version of each feature every product pins.