Skip to content

Make v1 the default arithmetic convention (Stage 2) #845

Description

@FBumann

Note

The following was generated by AI.

Tracks Stage 2 of the v1 arithmetic-convention rollout (opt-in → default → 1.0). v1 shipped opt-in in #717 (linopy.options["semantics"] = "v1", legacy the default). This issue is the decision and work to flip the default to v1.

Prerequisites (done)

  • v1 opt-in released — feat: v1 semantic convention #717
  • Transition surface complete — every legacy→v1 divergence warns under legacy (LinopySemanticsWarning, naming the fix)
  • Migration guide — doc/migrating-to-v1.rst

To make v1 the default

  • Pick the release for the flip — a pre-1.0 minor, so 1.0 can ship legacy-free (Remove legacy semantics at linopy 1.0 (Stage 3) #846). The flip must precede 1.0; otherwise it collides with the removal in a single release, leaving no window where v1 is the default and legacy is still opt-out.
  • Flip the options["semantics"] default to "v1". Legacy stays reachable via options["semantics"] = "legacy" from the flip through to 1.0 (however many minors that spans), and is removed at 1.0.
  • Add a dedicated opt-out deprecation warning: once v1 is the default, setting options["semantics"] = "legacy" emits a "legacy is deprecated, removed at 1.0" signal — distinct from the per-site LinopySemanticsWarning (which flags behaviour changes, not "on borrowed time"). Use whichever unified warning channel Unify deprecation warning channels before v1: EvolvingAPIWarning vs LinopySemanticsWarning #738 settles on.
  • Gate the flip on downstream readiness — the check-in in Plan: v1 semantics community discussion (open after #717 merges) #857 (PyPSA, PyPSA-Eur, Calliope, flixopt) so they opt in / pin before it lands.
  • Announce ahead of time: changelog note + downstream heads-up.
  • Re-frame any docs/notebooks that still describe legacy as the default.

The LinopySemanticsWarning is a FutureWarning firing since the opt-in release (#717), so the deprecation runway is already long by the time of the flip.

Legacy removal is a separate 1.0 step (arithmetics-design/legacy-removal.md). Spec: arithmetics-design/convention.md; rollout: arithmetics-design/open-items.md.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Fields

    No fields configured for issues without a type.

    Projects

    No projects

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions