Build and release processes

Publishing to PyPI

This guide explains how to publish a new version of the ElectionBuddy Python package to PyPI.

Prerequisites

• VS Code with Remote Containers extension
• Project cloned locally

Steps

1. Set up PyPI credentials

1. Copy the environment file:

   cp .devcontainer/.env.sample .devcontainer/.env

2. Get the PyPI token

3. Update the environment file:

   • Open .devcontainer/.env
   • Replace your-token-here with the token you copied from 1Password

   PYPI_TOKEN=your-token-here

2. Build the package

1. Make sure you're in the project root directory
2. Run the build command:

   hatch build

   This will create distribution files in the dist/ directory.

3. Publish to PyPI

1. Upload the distribution files:

   twine upload dist/*

2. Verify the upload:

   • Visit https://pypi.org/project/electionbuddy-python/
   • Check that the new version is listed

Troubleshooting

• If you get authentication errors, make sure the token in your .env file is correct and the container was rebuilt after updating it
• If twine upload fails, try running twine check dist/* first to validate the distribution files
• If you need to rebuild the dev container:
  1. Open Command Palette (Ctrl/Cmd + Shift + P)
  2. Search for "Dev Containers: Rebuild Container"

Notes

• The .env file is gitignored and should never be committed
• Each new release requires updating the version in src/electionbuddy_python/__about__.py
• If you need to test the release process, consider using TestPyPI first