feature:upgrade

Introduction
Previewing the plan
Upgrading some features
Pinning an editable feature
How the plan is made
Keeping the migration history
What applying changes
Reference
Requirements
See also

Introduction

feature:upgrade moves your product’s features to the newest versions that install together. pip makes the plan, a version that would rewrite a feature’s migration history is refused, and applying changes only the pins.

splent feature:upgrade

  feature:upgrade  my_product

    Feature             Pinned   Planned
    notes               v1.6.2   v1.18.0  upgrade, adds 1 migration
    shop                v1.0.2   v1.5.0   upgrade

  Migrations db:upgrade will apply
    notes  notes0002_visibility  Add visibility to notes (private unless the product says otherwise).

  Upgrade 2 features as planned? [y/N]: y

  Applying
    pin      notes v1.6.2 to v1.18.0
    pin      shop v1.0.2 to v1.5.0
  ...
  Next steps
    splent product:derive    installs the new versions and restarts the product
    splent db:upgrade        applies the 1 new migration listed above

Nothing in the product changes until the plan holds and you confirm it. Applying is all or nothing.

Previewing the plan

splent feature:upgrade --dry-run

It prints the plan and writes nothing. In CI, pass --yes instead to skip the prompt.

Upgrading some features

splent feature:upgrade notes shop

The rest stay at their pins. A name can be notes, splent_feature_notes or splent-io/splent_feature_notes.

Pinning an editable feature

splent feature:upgrade reports

A whole-product upgrade leaves editable features alone, so name one to pin it. The copy must be a git checkout with the release tag and nothing after it, committed or not.

  Not upgraded
    reports  the editable copy has 2 commits after v0.3.0 that no release has. Pinning it to v0.3.0 would drop them, so it stays editable. Release them first with splent feature:release.

How the plan is made

pip resolves against PyPI without installing anything. It gets the upgraded features at or above their pins, the rest at their pins, your framework range and the newest splent_cli, as the production image installs it.

Case	What the plan does
A tag PyPI does not serve	Takes the newest version PyPI serves
A version that does not install with the rest	Takes an older one
A version on PyPI the forge has not tagged	Refuses it
A feature or pin PyPI does not serve	Leaves it as it is
A feature pinned differently in two lists	Leaves it alone until the pins agree

Keeping the migration history

The new version must ship every migration of the pinned one, each with the same parent. Otherwise it is refused and stays at its pin, since your database would point at history the new code lacks.

Read the migrations the plan lists before you run db:upgrade. Some need a decision from the product first (see A migration that needs a decision).

What applying changes

The new versions are cloned into .splent_cache, then only the pins in pyproject.toml change, with comments and layout kept. The links in features/<namespace>/ move, recorded as declared. If a release cannot be fetched, nothing changes.

Then the config, compat and refinement phases of product:validate run. A failure is not rolled back, so fix it or restore the old pins. On success the product’s CI workflows follow the new pins (see Keeping the workflows in step).

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

It exits 1 when pip cannot resolve the set, applying fails, a feature was refused or validation fails. A dry run exits 0 unless pip cannot resolve.

Message	What to do
`pip could not resolve the set.`	Read pip’s explanation
`'<name>' is not declared in this product.`	Check the name
`pip is not installed in the Python the CLI runs on ...`	Run `python -m ensurepip`
`The forge rate limit stopped the check of <repo> (HTTP 403).`	Set `SPLENT_FORGE_TOKEN`
`Could not check 1 feature on PyPI (cache, HTTP 429).`	Run again later
`Nothing in the product was changed.`	Fix what the line above says

Requirements

A selected product (SPLENT_APP).
pip in the Python the CLI runs on.
SPLENT_FORGE_TOKEN (or GITHUB_TOKEN) raises the forge’s rate limit.