Skip to content

Releasing

Jump to bottom
brookie edited this page Nov 7, 2026 · 2 revisions

Releasing

How to publish a new version to PyPI (and a desktop app release on GitHub). Every step is a block you can copy and paste. Run them from the financial_planner folder.

Contents

One-time setup

  1. Create accounts on pypi.org and test.pypi.org (separate accounts) and turn on two-factor authentication.
  2. Create an API token on each: Account settings › API tokens › Add API token. For the very first upload the scope must be "Entire account"; after the project exists you can replace it with a token scoped to financial-planner.
  3. Save both tokens in ~/.pypirc (paste your tokens in place of the pypi-… placeholders):
cat > ~/.pypirc <<'EOF'
[distutils]
index-servers =
    pypi
    testpypi

[pypi]
username = __token__
password = pypi-PASTE-YOUR-PYPI-TOKEN-HERE

[testpypi]
repository = https://test.pypi.org/legacy/
username = __token__
password = pypi-PASTE-YOUR-TESTPYPI-TOKEN-HERE
EOF
chmod 600 ~/.pypirc
  1. Make sure the dev environment is installed (it includes build and twine):
pixi install -e dev

1. Set the version

The version lives in one place, src/financial_planner/__init__.py. Set the new one (use semantic versioning: bug fix 0.1.1, new features 0.2.0):

2. Test

pixi run -e dev test-all

Python tests and the forecast-math tests must all pass.

3. Build and check

Rebuilds the web app, builds the package into dist/ and checks it:

pixi run -e dev dist-check

You should see Successfully built financial_planner-<version>… and two PASSED lines.

4. Try it on TestPyPI

Upload to the test server:

pixi run -e dev publish-test

Install it from there in a throwaway environment and open the demo (dependencies come from the real PyPI):

rm -rf /tmp/fp-test && python3 -m venv /tmp/fp-test
/tmp/fp-test/bin/pip install --index-url https://test.pypi.org/simple/ \
  --extra-index-url https://pypi.org/simple/ "financial-planner[desktop]==$VERSION"
/tmp/fp-test/bin/financial_plan init /tmp/fp-test/demo --demo
/tmp/fp-test/bin/financial_plan start /tmp/fp-test/demo

The demo opens in your browser. Press Ctrl+C to stop, then clean up:

rm -rf /tmp/fp-test

TestPyPI never accepts the same version twice; to retry, bump to e.g. 0.1.1rc1 in step 1.

5. Publish to PyPI

pixi run -e dev publish

This rebuilds and checks first, then uploads. The project page is https://pypi.org/project/financial-planner/.

6. Tag and push

Commit the version change, tag the release and push both:

git add src/financial_planner/__init__.py pixi.lock
git commit -m "(release) __init__.py: v$VERSION"
git tag -a "v$VERSION" -m "v$VERSION"
git push && git push --tags

Create the GitHub release (needs the GitHub CLI, gh auth login once):

gh release create "v$VERSION" --title "v$VERSION" --generate-notes dist/*

7. Desktop app release (optional)

Build the no-code Mac apps (Apple Silicon and Intel) and attach them to the release:

bash installer/macos/make-dist.sh
gh release upload "v$VERSION" installer/dist/FinancialPlanner-macos-arm64.zip installer/dist/FinancialPlanner-macos-x86_64.zip

Rebuild your own installed app from the release too:

bash installer/macos/make-local-app.sh

8. Check the release

Install from the real PyPI in a fresh environment:

rm -rf /tmp/fp-check && python3 -m venv /tmp/fp-check
/tmp/fp-check/bin/pip install "financial-planner[desktop]==$VERSION"
/tmp/fp-check/bin/financial_plan --help
rm -rf /tmp/fp-check

People can now install it with pip install financial-planner (add [desktop] for the Mac menu-bar app), or in a pixi project with:

[pypi-dependencies]
financial-planner = { version = ">=0.1", extras = ["desktop"] }

How the desktop app gets updates

The desktop app installs financial-planner from PyPI (installer/manifest/pixi.toml allows any 0.x version), so:

  • A new install gets the newest 0.x release; no git or developer tools needed.
  • Check for Updates… in the menu-bar icon picks up each new PyPI release. Pushing to GitHub alone doesn't reach desktop users; publishing does.
  • Going to 1.0: widen the range in the manifest (e.g. ">=0.1,<2") and rebuild the app zips (step 7), since existing apps won't cross the upper bound.

Fixing a bad release

PyPI never lets you re-upload a version number. Fix the problem, bump the version (e.g. 0.1.1) and release again. To hide a broken version from installs, yank it on its PyPI page (Manage › Releases › Options › Yank); it stays downloadable only for people who pin it exactly.

What's in the package

  • The Python package with the built web app (src/financial_planner/web/, so users don't need Node), the app icons, the blank plan template and the demo plan (copied into the package at build time).
  • The financial_plan command.
  • Optional extras: desktop (pystray + Pillow for the menu-bar app) and dev (pytest, httpx).

The source package (.tar.gz) leaves out web/node_modules, built app zips and the README's assets/ folder.

🏠 Home

Getting started

Using the app

Setting up your plan

Reference

Clone this wiki locally