Releases¶

PyFDS release process and version management.

Overview¶

PyFDS follows semantic versioning and maintains a clear release process to ensure stability and predictability for users.

Versioning¶

Semantic Versioning¶

PyFDS uses Semantic Versioning 2.0.0:

MAJOR.MINOR.PATCH

MAJOR: Breaking changes to public API
MINOR: New features, backward compatible
PATCH: Bug fixes, backward compatible

Examples:

0.1.0 → 0.2.0: Added new namelists (MINOR)
0.2.0 → 0.2.1: Fixed validation bug (PATCH)
0.2.1 → 1.0.0: Stable API, breaking changes (MAJOR)

Version File¶

Version is defined in src/pyfds/__init__.py:

__version__ = "0.1.0"

Release Process¶

1. Prepare Release¶

Update Version

# Edit version
vim src/pyfds/__init__.py

# Update __version__ = "0.2.0"

Update Changelog

# Edit CHANGELOG.md
vim CHANGELOG.md

Add release notes:

## [0.2.0] - -11-26

### Added
- VENT namelist support
- MISC namelist for global settings
- Validation for mesh quality

### Changed
- Improved error messages
- Updated documentation

### Fixed
- Mesh bounds validation
- Reference checking for SURF_ID

### Deprecated
- Old mesh() API (use new signature)

2. Run Tests¶

Ensure all tests pass:

# Run full test suite
uv run pytest

# Run with coverage
uv run pytest --cov=pyfds --cov-report=html

# Check coverage threshold
uv run pytest --cov=pyfds --cov-fail-under=80

3. Build Documentation¶

Build and verify documentation:

# Build docs
uv run mkdocs build --strict

# Serve locally to verify
uv run mkdocs serve

# Check for broken links
# (manually review)

4. Create Git Tag¶

# Commit version changes
git add src/pyfds/__init__.py CHANGELOG.md
git commit -m "Bump version to 0.2.0"

# Create tag
git tag -a v0.2.0 -m "Release version 0.2.0"

# Push tag
git push origin v0.2.0

5. Build Package¶

# Clean previous builds
rm -rf dist/

# Build package
uv build

# Check built package
ls -lh dist/
# pyfds-0.2.0-py3-none-any.whl
# pyfds-0.2.0.tar.gz

6. Publish to PyPI¶

Test PyPI (optional)

# Upload to test PyPI
uv publish --repository testpypi

# Test installation
pip install --index-url https://test.pypi.org/simple/ pyfds==0.2.0

Production PyPI

# Upload to PyPI
uv publish

# Verify on PyPI
# https://pypi.org/project/pyfds/

7. GitHub Release¶

Create release on GitHub:

Go to: https://github.com/GraysonBellamy/pyfds/releases/new
Select tag: v0.2.0
Title: "PyFDS v0.2.0"
Description: Copy from CHANGELOG.md
Attach built packages (optional)
Click "Publish release"

8. Update Documentation¶

Documentation is automatically deployed via GitHub Actions when pushing to main.

Verify deployment: - https://graysonbellamy.github.io/pyfds

Release Checklist¶

Use this checklist for each release:

## Pre-Release

- [ ] All tests passing
- [ ] Coverage meets threshold (80%+)
- [ ] Documentation builds without warnings
- [ ] CHANGELOG.md updated
- [ ] Version bumped in __init__.py
- [ ] All issues in milestone closed

## Release

- [ ] Git tag created (v0.x.x)
- [ ] Tag pushed to GitHub
- [ ] Package built successfully
- [ ] Uploaded to PyPI
- [ ] GitHub release created
- [ ] Documentation deployed

## Post-Release

- [ ] Verify PyPI package installable
- [ ] Verify documentation live
- [ ] Announcement posted (if major release)
- [ ] Milestone closed
- [ ] Next milestone created

Version Management¶

Development Version¶

During development, use .dev suffix:

__version__ = "0.2.0.dev"

Release Candidates¶

For major releases, create release candidates:

__version__ = "1.0.0rc1"

Test thoroughly before final release:

# Tag RC
git tag -a v1.0.0rc1 -m "Release candidate 1"

# Build and test
uv build
uv publish --repository testpypi

# After testing, release final
__version__ = "1.0.0"
git tag -a v1.0.0 -m "Release version 1.0.0"

Changelog Format¶

Follow Keep a Changelog format:

# Changelog

All notable changes to PyFDS will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [Unreleased]

### Added
- Feature in development

## [0.2.0] - -11-26

### Added
- New features

### Changed
- Improvements

### Deprecated
- Features to be removed

### Removed
- Removed features

### Fixed
- Bug fixes

### Security
- Security fixes

## [0.1.0] - -10-15

Initial release

Automated Releases¶

GitHub Actions¶

Automate releases with GitHub Actions:

# .github/workflows/release.yml
name: Release

on:
  push:
    tags:
      - 'v*'

jobs:
  release:
    runs-on: ubuntu-latest

    steps:
    - uses: actions/checkout@v3

    - name: Install uv
      uses: astral-sh/setup-uv@v1

    - name: Set up Python
      run: uv python install 3.11

    - name: Install dependencies
      run: uv sync

    - name: Run tests
      run: uv run pytest --cov=pyfds --cov-fail-under=80

    - name: Build package
      run: uv build

    - name: Publish to PyPI
      env:
        UV_PUBLISH_TOKEN: ${{ secrets.PYPI_API_TOKEN }}
      run: uv publish

    - name: Create GitHub Release
      uses: softprops/action-gh-release@v1
      with:
        files: dist/*
        generate_release_notes: true

Setup PyPI Token¶

Create API token on PyPI
Add to GitHub secrets as PYPI_API_TOKEN
Token is used automatically in workflow

Deprecation Policy¶

Deprecating Features¶

Announce deprecation in release notes
Add deprecation warning:

import warnings

def old_function():
    warnings.warn(
        "old_function is deprecated, use new_function instead",
        DeprecationWarning,
        stacklevel=2
    )
    return new_function()

Keep for at least 2 minor versions
Remove in next major version

Example Timeline:

v0.3.0: Feature deprecated, warning added
v0.4.0: Still available with warning
v0.5.0: Still available with warning
v1.0.0: Feature removed

Breaking Changes¶

When to Release Major Version¶

Release major version (1.0.0, 2.0.0) when:

Breaking API changes
Removing deprecated features
Major architectural changes
Incompatible file format changes

How to Handle Breaking Changes¶

Document clearly in CHANGELOG
Provide migration guide
Update examples
Consider providing compatibility layer (temporarily)

Migration Guide Example:

## Migrating from 0.x to 1.0

### Mesh API Changed

**Before (0.x)**:
```python
sim.add_mesh(50, 50, 25, 0, 5, 0, 5, 0, 2.5)

After (1.0):

sim.add(Mesh(ijk=Grid3D.of(50, 50, 25), xb=Bounds3D.of(0, 5, 0, 5, 0, 2.5)))

Surface API Simplified¶

Before (0.x):

sim.add_surface('FIRE', {'HRRPUA': 1000.0})