# PyFulmen v0.1.8 Release Notes

**Release Date**: October 29, 2025  
**Type**: Infrastructure & Quality  
**Status**: ✅ Released

## Overview

PyFulmen v0.1.8 establishes production-grade CI/CD infrastructure and fixes critical dependency issues for public release readiness. This release introduces comprehensive GitHub Actions workflows for automated testing across Ubuntu and macOS platforms, corrects the rapidfuzz dependency classification for Similarity v2.0.0, and significantly improves test reliability.

## Highlights

### 🚀 CI/CD Infrastructure

**GitHub Actions Workflows**:

- **Test Matrix**: 4 combinations (Ubuntu/macOS × Python 3.12/3.13)
- **Quality Gates**: Linting, formatting, test coverage
- **Package Validation**: Build checks and metadata verification
- **Coverage Tracking**: Codecov integration (optional)

### 🔧 Dependency Corrections

**rapidfuzz Required Runtime Dependency**:

- Moved from optional dev dependency to main dependencies (≥3.14.1)
- Similarity v2.0.0 metrics require rapidfuzz for correct implementations:
  - Damerau-Levenshtein OSA/Unrestricted
  - Jaro-Winkler
- Removed incorrect fallback algorithms that returned wrong results

### 🧪 Test Reliability

**Platform-Conditional Testing**:

- Tests run on their native platform (macOS tests on macOS, Linux on Linux)
- Replaced complex mock-based tests with `pytest.skip` conditionals
- Reality-check tests using environment variables instead of fragile mocks
- Performance test thresholds adjusted for CI runner characteristics

## What's New

### Added

- GitHub Actions CI/CD workflows (`test.yml`, `build.yml`)
- Platform-conditional path tests (macOS/Linux/Windows)
- Reality-check tests for actual platform behavior validation
- Project URLs in `pyproject.toml` (Homepage, Documentation, Repository, Changelog)

### Changed

- **rapidfuzz ≥3.14.1 now required at runtime** (breaking change)
- Crucible sync updated to v0.2.2 (from v0.2.1)
- Performance test overhead threshold: 200% → 600% (CI runner allowance)

### Fixed

- Removed incorrect Similarity fallback algorithms (Damerau → Levenshtein, Jaro-Winkler → exact match)
- Platform-specific path tests no longer fragile across different OS environments
- Import sorting issues in test files (ruff I001)

## Breaking Changes

### rapidfuzz Dependency

**Before v0.1.8** (optional):

```toml
[project.optional-dependencies]
dev = ["rapidfuzz>=3.14.1", ...]
```

**After v0.1.8** (required):

```toml
[project]
dependencies = ["rapidfuzz>=3.14.1", ...]
```

**Impact**: Applications using Similarity v2.0.0 metrics must have rapidfuzz installed.

**Migration**: No code changes required - rapidfuzz is now automatically installed.

## Quality Metrics

- ✅ **1286 tests passing** (19 skipped platform-specific)
- ✅ **93% code coverage**
- ✅ **CI passing**: Ubuntu + macOS runners
- ✅ **Package validation**: `twine check` passing
- ✅ **Zero linting errors**: `ruff check` clean
- ✅ **Proper formatting**: `ruff format` compliant

## Lessons Learned

### Testing Philosophy

**Avoid Complex Mocking**:

- Platform-conditional tests (`pytest.skip`) > fragile mocks
- Environment variables > mocking classmethods
- Reality checks > mock correctness validation

**Example - Before** (fragile):

```python
@patch("pyfulmen.config.paths.Path.home")  # Breaks with import-time bindings
def test_macos_paths(mock_home):
    ...
```

**Example - After** (robust):

```python
def test_macos_paths_on_real_macos():
    if sys.platform != "darwin":
        pytest.skip("macOS-specific test")
    # Test actual behavior on macOS
    ...
```

### CI/CD Best Practices

1. **Use `uv tool run` for one-off tools** - don't install via pip
2. **Matrix testing catches platform-specific issues** early
3. **Performance thresholds must account for CI runners** (slower than local dev)
4. **Reality-check tests validate actual behavior** better than mocks

## Upgrade Guide

### From v0.1.7

```bash
# Using pip
pip install --upgrade pyfulmen

# Using uv
uv pip install --upgrade pyfulmen
```

**No code changes required** - rapidfuzz is now automatically included as a runtime dependency.

### Verify Installation

```python
from pyfulmen.foundry import similarity

# Damerau-Levenshtein requires rapidfuzz
distance = similarity.distance("hello", "helo", metric="damerau_osa")
assert distance == 1  # Transposition distance
```

## Contributors

- PyFulmen Architect (@pyfulmen-architect)
- Dave Thompson (@3leapsdave)

## References

- [CHANGELOG](../../CHANGELOG.md#018---2025-10-29)
- [GitHub Actions Workflows](../../.github/workflows/)
- [Similarity v2.0.0 Documentation](../foundry/similarity/README.md)
- [Crucible v0.2.2](https://github.com/fulmenhq/crucible/releases/tag/v0.2.2)

---

**Full Changelog**: [v0.1.7...v0.1.8](https://github.com/fulmenhq/pyfulmen/compare/v0.1.7...v0.1.8)
