Skip to content

PUBLISHING.md

Latest commit

 

History

History
194 lines (136 loc) · 3.27 KB

PUBLISHING.md

File metadata and controls

194 lines (136 loc) · 3.27 KB

Publishing Guide

1. Install and Setup pyenv with Python 3.12.10

Install pyenv

macOS (Homebrew):

brew install pyenv

Linux:

curl https://pyenv.run | bash

Add the following to your shell config (~/.zshrc or ~/.bashrc):

export PYENV_ROOT="$HOME/.pyenv"
export PATH="$PYENV_ROOT/bin:$PATH"
eval "$(pyenv init -)"

Reload your shell:

source ~/.zshrc   # or source ~/.bashrc

Install Python 3.12.10

pyenv install 3.12.10

Create a Virtual Environment

pyenv shell 3.12.10
python -m venv .venv
source .venv/bin/activate

Confirm the Python version:

python --version
# Python 3.12.10

2. Install Required Packages

With the virtual environment active:

pip install --upgrade pip
pip install build twine

3. Bump the Version

Before every release, update the version in two places so they stay in sync.

pyproject.toml:

[project]
name = "onefuse"
version = "2026.2.0"   # <-- update this

onefuse/__init__.py:

__version__ = "2026.2.0"   # <-- update this to match

The version scheme used in this project is YYYY.MINOR.PATCH (e.g. 2026.1.0, 2026.1.1, 2026.2.0).

Note: PyPI does not allow re-uploading the same version. Always bump before building.

4. Build and Publish to TestPyPI

Use TestPyPI to verify the package before publishing to the real index.

Create a TestPyPI Account

  1. Register at https://test.pypi.org
  2. Go to Account Settings → API tokens
  3. Create a token scoped to Entire account

Store Credentials (optional)

Add the following to ~/.pypirc to avoid being prompted each time:

[testpypi]
username = __token__
password = pypi-your-testpypi-token-here

Build

rm -rf dist/
python -m build

Validate

twine check dist/*

Upload to TestPyPI

twine upload --repository testpypi dist/*

When prompted:

  • Username: __token__
  • Password: your TestPyPI API token

Install from TestPyPI

pip install --index-url https://test.pypi.org/simple/ onefuse

Verify the installed version:

python -c "import onefuse; print(onefuse.__version__)"

5. Build and Publish to PyPI

Only proceed here after successfully verifying the package on TestPyPI.

Create a PyPI Account

  1. Register at https://pypi.org
  2. Go to Account Settings → API tokens
  3. Create a token scoped to Entire account (or to the onefuse project once it exists)

Store Credentials (optional)

Add the following to ~/.pypirc:

[pypi]
username = __token__
password = pypi-your-pypi-token-here

Build

rm -rf dist/
python -m build

Validate

twine check dist/*

Upload to PyPI

twine upload dist/*

When prompted:

  • Username: __token__
  • Password: your PyPI API token

Install from PyPI

pip install onefuse

Verify the installed version:

python -c "import onefuse; print(onefuse.__version__)"

Note: PyPI does not allow re-uploading the same version. If a release needs to be corrected after uploading, return to Section 3 to bump the version before building and uploading again.