This document provides step-by-step instructions for releasing a new version of hedtools to PyPI.

Platform Support: This guide includes commands for both Windows (PowerShell) and Linux/macOS (Bash).

Before starting the release process, ensure you have:

• Write access to the hed-python repository
• PyPI account with maintainer access to the hedtools package
• Git configured with your credentials
• Python 3.10+ installed
• Virtual environment activated (if using one)
• All intended changes merged to the main branch

Windows (PowerShell):

# Check git status
git status

# If there are uncommitted changes, commit or stash them
git add .
git commit -m "Pre-release cleanup"

Linux/macOS (Bash):

# Check git status
git status

# If there are uncommitted changes, commit or stash them
git add .
git commit -m "Pre-release cleanup"

Add a new entry at the top of CHANGELOG.md with:

• Release version number (e.g., "Release 0.7.1")
• Release date
• Bullet points describing:
  • New features
  • Enhancements
  • Bug fixes
  • Documentation improvements
  • Breaking changes (if any)

Example:

Release 0.7.1 October 13, 2025
- Applied Black code formatter to entire codebase for consistent code style
- Added Black to development dependencies and CI workflow
- Enhanced CONTRIBUTING.md with code formatting guidelines
- Updated README.md with Black usage instructions

Before releasing, ensure all code quality checks pass:

All Platforms:

# Run code formatter check
black --check .
# On Windows, use: black --workers 1 --check .

# Run linter
ruff check hed/ tests/

# Run spell checker
codespell

# Run all tests
python -m unittest discover tests -v

Fix any issues before proceeding.

All Platforms:

git add CHANGELOG.md
git commit -m "Update CHANGELOG for version 0.7.1"

If you're working on a feature branch:

All Platforms:

# Update your local main branch
git checkout main
git pull origin main

# Merge your feature branch
git merge your-feature-branch

# Resolve any conflicts if they arise
# Then push to origin
git push origin main

The project uses versioneer for version management, which automatically derives the version from git tags.

All Platforms:

# Create an annotated tag with the version number
git tag -a 0.7.0 -m "Release version 0.7.0"

Important:

• Use semantic versioning: MAJOR.MINOR.PATCH
• Do NOT use a prefix (e.g., use 0.7.0, not v0.7.0)
• The tag name must match the version you want to release

All Platforms:

# Push the tag to the remote repository
git push origin 0.7.0

All Platforms:

# Check that the version is correctly detected
python -c "import hed; print(hed.__version__)"

Expected output: 0.7.0

If you see something like 0+untagged.xxx.gxxxxxxx, the tag wasn't properly created or you need to pull the tags:

All Platforms:

git fetch --tags

Windows (PowerShell):

# Remove old build artifacts
Remove-Item -Recurse -Force dist, build, *.egg-info -ErrorAction SilentlyContinue

Linux/macOS (Bash):

# Remove old build artifacts
rm -rf dist build *.egg-info

All Platforms:

python -m pip install --upgrade build twine

All Platforms:

# Build both wheel and source distributions
python -m build

This creates:

• dist/hedtools-0.7.0-py3-none-any.whl (wheel distribution)
• dist/hedtools-0.7.0.tar.gz (source distribution)

Windows (PowerShell):

# List contents of the wheel
python -m zipfile -l dist/hedtools-0.7.0-py3-none-any.whl

# Check the source distribution (requires tar in PATH)
tar -tzf dist/hedtools-0.7.0.tar.gz

Linux/macOS (Bash):

# List contents of the wheel
unzip -l dist/hedtools-0.7.0-py3-none-any.whl

# Check the source distribution
tar -tzf dist/hedtools-0.7.0.tar.gz

Windows (PowerShell):

# Create a fresh virtual environment for testing
python -m venv test_env
.\test_env\Scripts\Activate.ps1

Linux/macOS (Bash):

# Create a fresh virtual environment for testing
python -m venv test_env
source test_env/bin/activate

All Platforms:

# Install the built wheel
pip install dist/hedtools-0.7.0-py3-none-any.whl

Windows (PowerShell):

# Navigate back to the repository
cd h:\Repos\hed-python

# Run the test suite
python -m unittest discover tests -v

Linux/macOS (Bash):

# Navigate back to the repository
cd ~/path/to/hed-python

# Run the test suite
python -m unittest discover tests -v

All Platforms:

# Check version
python -c "import hed; print(hed.__version__)"

# Test a basic import
python -c "from hed import load_schema_version; schema = load_schema_version('8.3.0'); print('Success!')"

Windows (PowerShell):

deactivate
Remove-Item -Recurse -Force test_env

Linux/macOS (Bash):

deactivate
rm -rf test_env

All Platforms:

# Validate the distribution packages
python -m twine check dist/*

Expected output: Checking dist/hedtools-0.7.0.tar.gz: PASSED (and same for .whl)

All Platforms:

# Upload to TestPyPI first
python -m twine upload --repository testpypi dist/*

You'll be prompted for your TestPyPI credentials.

Test installation from TestPyPI:

pip install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ hedtools==0.7.0

All Platforms:

# Upload to the real PyPI
python -m twine upload dist/*

You'll be prompted for your PyPI credentials (or use an API token).

Alternative with API Token:

Windows (PowerShell):

# Set your PyPI API token as an environment variable
$env:TWINE_USERNAME = "__token__"
$env:TWINE_PASSWORD = "pypi-your-api-token-here"

# Upload
python -m twine upload dist/*

Linux/macOS (Bash):

# Set your PyPI API token as an environment variable
export TWINE_USERNAME="__token__"
export TWINE_PASSWORD="pypi-your-api-token-here"

# Upload
python -m twine upload dist/*

Visit https://pypi.org/project/hedtools/ and verify:

• Version 0.7.0 is listed
• README renders correctly
• All metadata is correct
• Download links work

Go to: https://github.com/hed-standard/hed-python/releases/new

Fill in the release form:

• Choose a tag: Select 0.7.0 from the dropdown
• Release title: Release 0.7.0
• Description: Copy the relevant section from CHANGELOG.md

Example description:

## What's New in 0.7.0

### Features
- Added comprehensive logging infrastructure with configurable log levels and file output
- Enhanced validate_bids script with improved error reporting and filtering capabilities
- Added error code counting and filtering by count/file in ErrorHandler

### Documentation
- Added comprehensive CONTRIBUTING.md with development guidelines
- Significantly enhanced README.md with better documentation structure
- Improved user guide documentation

### Bug Fixes
- Fixed Windows path handling in tests
- Fixed typos and improved code documentation

### Full Changelog
See [CHANGELOG.md](https://github.com/hed-standard/hed-python/blob/main/CHANGELOG.md)

• Upload dist/hedtools-0.7.0-py3-none-any.whl
• Upload dist/hedtools-0.7.0.tar.gz

Click Publish release

In a fresh environment:

All Platforms:

pip install --upgrade hedtools
python -c "import hed; print(hed.__version__)"

Expected output: 0.7.0

Check that documentation sites are updated (may take some time):

• https://www.hedtags.org/hed-python/

Consider announcing the release:

• GitHub Discussions
• HED mailing list
• Community forums
• Social media (if applicable)

Problem: python -c "import hed; print(hed.__version__)" shows wrong version

Solution:

# Fetch all tags
git fetch --tags

# Verify tag exists
git tag -l

# Check versioneer can find it
python -c "import hed._version; print(hed._version.get_versions())"

Problem: Missing dependencies during build

Solution:

# Ensure build tools are installed
pip install --upgrade pip setuptools wheel build

# Try building again
python -m build

Problem: Invalid credentials or API token

Solution:

• Create a new API token at https://pypi.org/manage/account/token/
• Scope it to the hedtools project only
• Use __token__ as username and the token as password

Problem: You need to delete and recreate a tag

Solution:

# Delete local tag
git tag -d 0.7.0

# Delete remote tag (CAUTION: only if not yet released!)
git push origin :refs/tags/0.7.0

# Recreate the tag
git tag -a 0.7.0 -m "Release version 0.7.0"
git push origin 0.7.0

WARNING: Only delete remote tags if the release hasn't been published yet!

HED-Python follows Semantic Versioning:

• MAJOR version (X.0.0): Incompatible API changes
• MINOR version (0.X.0): New features, backward-compatible
• PATCH version (0.0.X): Bug fixes, backward-compatible

• MAJOR: Breaking changes, API redesign, major architectural changes
• MINOR: New features, new functions/classes, enhancements (this release: 0.7.0)
• PATCH: Bug fixes, documentation fixes, small improvements (0.7.1)

Windows (PowerShell):

# Complete release workflow
git status                                    # Check working tree
git add CHANGELOG.md                          # Stage changelog
git commit -m "Update CHANGELOG for v0.7.0"   # Commit
git push origin main                          # Push to main
git tag -a 0.7.0 -m "Release version 0.7.0"   # Create tag
git push origin 0.7.0                         # Push tag
Remove-Item -Recurse -Force dist, build, *.egg-info -ErrorAction SilentlyContinue
python -m build                               # Build
python -m twine check dist/*                  # Verify
python -m twine upload dist/*                 # Upload

Linux/macOS (Bash):

# Complete release workflow
git status                                    # Check working tree
git add CHANGELOG.md                          # Stage changelog
git commit -m "Update CHANGELOG for 0.7.0"    # Commit
git push origin main                          # Push to main
git tag -a 0.7.0 -m "Release version 0.7.0"   # Create tag
git push origin 0.7.0                         # Push tag
rm -rf dist build *.egg-info                  # Clean old builds
python -m build                               # Build
python -m twine check dist/*                  # Verify
python -m twine upload dist/*                 # Upload

• Python Packaging Guide
• Versioneer Documentation
• PyPI Help
• Semantic Versioning
• HED Documentation

For questions about the release process:

• Maintainer: Kay Robbins ([email protected])
• Repository: https://github.com/hed-standard/hed-python
• Issues: https://github.com/hed-standard/hed-python/issues