Plan: v1 semantics community discussion (open after #717 merges)

[FBumann]

Note

This tracking issue was drafted with AI.

Plan for a community Q&A discussion on the v1 arithmetic semantics, to open after #717 merges (so the convention.md and migration-guide links resolve on master).

Prerequisites / checklist

• Enable GitHub Discussions on the repo — currently disabled (hasDiscussionsEnabled: false); a maintainer/admin repo setting.
• Merge feat: v1 semantic convention #717 and the doc follow-ups (docs(v1): cover unlabeled-operand and grouper cases; fold MI-level projection #855 migration-guide coverage, docs(v1): fix §11 MultiIndex-level projection example #856 §11 fix) so the links go live on master.
• Open a pinned Q&A discussion from the skeleton below.
• Cross-link the discussion from Meta: predictable arithmetic — coordinate alignment and NaN handling #714 (bug catalogue) and feat: v1 semantic convention #717 (the change).
• Notify downstream — PyPSA, PyPSA-Eur, Calliope, flixopt — with a short pointer in their repos (the discussion is passive; maintainers won't see it otherwise).

Why a discussion (and not just issues)

The discussion is the low-friction front door for "will this break my model?" / "intended or a bug?" questions, and Q&A answers can be marked into an FAQ. Concrete, reproducible breakages still get funneled to issues so they stay tracked.

Discussion skeleton (Q&A category, pinned) — draft

Intent line to be handwritten by the poster.

What's changing — linopy is introducing a stricter, opt-in arithmetic convention ("v1") that replaces legacy's silent guesses (filled NaN, positional joins, absent-as-zero) with explicit rules that raise, so a wrong model errors at build time instead of returning a wrong number.

• Rules: link arithmetics-design/convention.md
• Migrate: link doc/migrating-to-v1.rst (readthedocs)
• Fixes: Meta: predictable arithmetic — coordinate alignment and NaN handling #714 · Change: feat: v1 semantic convention #717

Timeline — (1) now: opt-in via linopy.options["semantics"] = "v1", legacy default + warns; (2) later minor: v1 default, legacy one more cycle; (3) 1.0: legacy removed.

Try it — set the option; to surface every site, run the suite under legacy with warnings.filterwarnings("error", category=LinopySemanticsWarning).

How to use the thread — questions here (answers marked → FAQ); concrete breakages / gaps in the guide → open an issue and link back; downstream maintainers especially wanted early.

FAQ seed — change anything today? (no) · a warning I don't own? (upstream; silence meanwhile) · why raise? (no silent wrong answers) · when default? (a later minor, announced here) · maintainer recipe? (opt in on a branch → warning-as-error → fix → run v1 → release).

Downstream notice template

linopy v1 arithmetic semantics — opt-in now, default later.
linopy is rolling out a stricter arithmetic convention that raises where it used to guess (NaN fills, positional joins, absent-as-zero). It's opt-in today and warns under legacy, becoming the default in a later release. This likely affects <library>; the migration guide (<link>) has a situation→fix table, and there's a discussion for questions: <link>. Opting in early on a branch (linopy.options["semantics"] = "v1") will surface what changes.