chore: release 0.1.0rc1

[FBumann]

Prompt: And prepare a todo list for me the same way. Also start with 0.1.0rc1

Note

The following content was generated by AI.

This is the release PR for 0.1.0rc1, the release candidate for the first PyPI upload. It is stacked on #1751. It stays a draft until PyPI can take the package. One direct reference is left, the linopy extra, and #1755 removes it (step 1).

The first PyPI release, step by step

1. What blocks the upload

PyPI refuses a distribution that names a git URL in its metadata.

• mathspec is on PyPI, and pyproject.toml depends on mathspec>=0.1.0 (build(deps): specsolve depends on the mathspec 0.1.0 release from PyPI rather than a git tag #1754). The parity job reads the corpus tag from that floor.
• Merge refactor(api): specsolve no longer builds a linopy model, and its linopy extra and LaneError are gone #1755. It takes linopy out of the package and keeps it as the test oracle: the linopy @ git+…@master reference moves to the dev group, which PyPI never sees. It also deletes allow-direct-references, so hatchling refuses a direct reference at build time, before PyPI would.

2. One-time setup

PyPI

• On pypi.org, go to Account → Publishing → "Add a new pending publisher" → GitHub, and fill in:
  • PyPI project name: specsolve
  • Owner: fluxopt
  • Repository name: specsolve
  • Workflow name: release.yaml
  • Environment name: pypi

GitHub, under fluxopt/specsolve Settings

• Environments: create or edit pypi. Under "Deployment branches and tags", choose "Selected branches and tags" and add main. Add the people who may approve a release as required reviewers.
• After ci: a release is a merged changelog heading, rather than a release-please PR merged automatically #1751 merges: Rules → the main ruleset. Require ci, Conventional commit subject and Changelog line. A required check must run on main once before you can require it.
• Issues → Labels: create no changelog.

Clean-up that the release does not need

• Delete the repository variables AUTO_RELEASE and PUBLISH_TO_PYPI if they exist. Turn off "Allow auto-merge" unless you want it for other PRs.
• Remove specsolve from the release app's (fluxopt-release-bot) repository access. If no other repository uses the app, uninstall it and delete the secrets APP_CLIENT_ID and APP_PRIVATE_KEY.
• Delete the branches release-please--branches--main--components--farkas and release-please--branches--main--components--linopy-yaml.
• Close chore: both direct references that block a PyPI upload are named #1675 and ci: a breaking change bumps the minor while releases stay alpha #1676. ci: a release is a merged changelog heading, rather than a release-please PR merged automatically #1751 replaces both.
• Open PRs owe a changelog line after ci: a release is a merged changelog heading, rather than a release-please PR merged automatically #1751 merges: test: a program that leaves a side of a bound open builds with that side unbounded in both engines #1737, feat(api): the feasible region of a model on two of its quantities is traced as a polygon #1527, feat(data): a table or a map short of what it declares is refused, so a row lost in preparation is not read as a mask #1516 and refactor(api): a linopy model is built by linopy rather than by this package #1541. refactor(api): a linopy model is built by linopy rather than by this package #1541 (drop the linopy lane for linopy's own from_spec) conflicts with refactor(api): specsolve no longer builds a linopy model, and its linopy extra and LaneError are gone #1755; close it or rebase it.

3. Before this PR merges: what the PyPI page shows

• [project.urls] has only repository. Add Documentation, Issues and Changelog, as docs: the installation page and the PyPI project page say pip install mathspec, and the README's links resolve on PyPI energy-models/mathspec#707 did.
• The README has two relative links, CONTRIBUTING.md and docs/about/prior-art.md. On PyPI they do not resolve. Make them absolute.
• src/specsolve/relational/parquet.py has two error messages that say "while the package is on 0.0.1aN". tests/test_archive.py asserts the same. Reword them to "before 1.0".
• RELEASING.md, "Relaxed while in early development": it says to tighten CI before 0.1.0, starting with a Python matrix behind the gate job. Do that, or change the sentence.

4. This PR

• Merge ci: a release is a merged changelog heading, rather than a release-please PR merged automatically #1751, then refactor(api): specsolve no longer builds a linopy model, and its linopy extra and LaneError are gone #1755. Then this PR's base must be main. GitHub retargets it when ci: a release is a merged changelog heading, rather than a release-please PR merged automatically #1751's branch is deleted; if the branch stays, retarget by hand.
• Mark the PR ready.
• Set the date in ## 0.1.0rc1 (2026-09-25) to the day you merge, if that is not the 25th.
• Edit the notes under the heading. Add the lines of the PRs merged since. The text becomes the GitHub release notes, as written.
• Check that ci is green. Its step "Check the changelog headings" prints releases 0.1.0rc1 on merge.
• Review, then squash-merge.

5. After the merge

• Actions → Release, the run for the merge commit:
  • Tag the version the changelog names created the tag v0.1.0rc1 and the GitHub release 0.1.0rc1, marked as a pre-release.
  • Build passed, and its check printed specsolve-0.1.0rc1.
  • Publish to PyPI waits for approval: "Review deployments" → pypi → Approve.
• https://pypi.org/project/specsolve/0.1.0rc1/ exists. The README renders, and the project links work.
• Smoke test in a fresh environment:

  python -m venv /tmp/ss && /tmp/ss/bin/pip install specsolve==0.1.0rc1
  /tmp/ss/bin/python -c "import specsolve, mathspec; print(specsolve.__version__, mathspec.__version__)"   # 0.1.0rc1 0.1.0
  /tmp/ss/bin/pip install specsolve   # finds no stable version until 0.1.0 exists

• If a job failed, fix the cause, then use "Re-run failed jobs" on that run. If 0.1.0rc1 reached PyPI broken, release 0.1.0rc2.

6. Then 0.1.0

• Open the next release PR, titled chore: release 0.1.0. It renames the next ## Upcoming version to ## 0.1.0 (date), with notes that say this is the first release on PyPI. Merge it and approve the upload as above.
• Smoke test pip install specsolve without a version. It should install 0.1.0.

7. Follow-ups

• 83 links in the tree point at math-spec.readthedocs.io. The redirect keeps them working. Point them at mathspec.readthedocs.io.
• Optional: a conda-forge recipe.
• Patch releases to an older version line. No path exists yet; mathspec tracks the same gap in A patch release to an older version line, such as 0.1.1 after main has moved to 0.2 energy-models/mathspec#710.

What this PR changes, what merging does, gates

The changes:

• CHANGELOG.md: an empty ## Upcoming version, then ## 0.1.0rc1 (2026-09-25), with a paragraph and docs: the solve example archives its run and reads it back, with annotations that name the other options #1748's line.
• AGENTS.md: "The project is 0.0.1aN and holds no compatibility promise" becomes "The project holds no compatibility promise before 1.0". One sentence is added: a release that breaks a model file or an import raises the minor version, and its notes name the break.
• CONTRIBUTING.md: the same rule, in the same words.

Why a release candidate: it goes through the same tag, GitHub release, build, approval and trusted-publishing upload as 0.1.0. The only addition is --prerelease on the GitHub release. pip skips it unless someone asks for it, so a broken first upload reaches no user. The version sorts after 0.0.1a358 and before 0.1.0.

What merging does: release.yaml finds 0.1.0rc1 with no tag. It creates v0.1.0rc1 and a GitHub pre-release, builds from the tag, checks that the wheel and the sdist are 0.1.0rc1, and waits for approval on pypi before the upload.

Gates: python -m tools.changelog check prints "releases 0.1.0rc1 on merge", and notes 0.1.0rc1 prints the section above. The suite on #1751's commit is in that PR. This commit changes only prose and the changelog.

Not verified: the name specsolve on PyPI. The PyPI API cannot be reached from this container, so check that the name is free when you add the pending publisher.

The type is chore, which owes no changelog line.

🤖 Generated with Claude Code

https://claude.ai/code/session_016Pv7LzSgzt7Yn2K3ioyJXw

[read-the-docs-community]

Documentation build overview

📚 specsolve | 🛠️ Build #34757565 | 📁 Comparing 606d0c8 against latest (c3d74e4)

  🔍 Preview build  

9 files changed · ± 9 modified

± Modified

• index.html
• about/architecture/index.html
• about/changelog/index.html
• about/linopy/index.html
• about/roadmap/index.html
• examples/pypsa_ladder/index.html
• howto/debug/index.html
• reference/api/index.html
• reference/glossary/index.html

[codspeed]

Merging this PR will not alter performance

✅ 24 untouched benchmarks
⏩ 82 skipped benchmarks¹

---

_{Comparing claude/release-0.1.0rc1 (606d0c8) with main (8c783ca)²}

Footnotes

1. 82 benchmarks were skipped, so the baseline results were used instead. If they were deleted from the codebase, click here and archive them to remove them from the performance reports. ↩

2. No successful run was found on main (a4be39a) during the generation of this report, so 8c783ca was used instead as the comparison base. There might be some changes unrelated to this pull request in this report. ↩