fAIr

Versioning Strategy and Backward Compatibility Policy

Last Updated: 2026-05-14
Current Version: 0.9.1

Overview

The Fairness Pipeline Development Toolkit follows Semantic Versioning (SemVer) to communicate the nature of changes in each release. This document outlines our versioning strategy, backward compatibility guarantees, deprecation policy, and migration guidance.

Semantic Versioning

Version numbers follow the format: MAJOR.MINOR.PATCH (e.g., 0.5.0)

Version Number Components

Current Status

Backward Compatibility Guarantees

Public API Stability

What is considered “Public API”?

The following are considered public APIs and maintain backward compatibility within the same major version:

  1. Public Classes and Functions exported in __init__.py files:
    • fairpipe.FairnessAnalyzer
    • fairpipe.MetricResult
    • fairpipe.assert_fairness
    • fairpipe.log_fairness_metrics
    • fairpipe.to_markdown_report
    • All classes and functions listed in __all__ of public modules
  2. CLI Commands and Arguments:
    • fairpipe version
    • fairpipe validate (with existing arguments)
    • fairpipe pipeline (with existing arguments)
    • fairpipe run-pipeline (with existing arguments)
    • fairpipe train-regularized, fairpipe train-lagrangian, fairpipe calibrate
  3. Configuration File Schema:
    • YAML configuration structure for PipelineConfig
    • Field names and types in configuration files
    • Default values and behavior
  4. Data Formats:
    • Input/output CSV formats
    • JSON artifact formats (reports, metrics)
    • MLflow logging structure

Compatibility Guarantees by Version Type

MAJOR Version (X.0.0)

MINOR Version (0.X.0)

PATCH Version (0.0.X)

Deprecation Policy

Deprecation Process

  1. Announcement: Deprecated features are announced in the CHANGELOG with a deprecation notice
  2. Warning Period: Deprecated features emit warnings when used (via warnings module)
  3. Documentation: Deprecation notices include:
    • Reason for deprecation
    • Recommended alternative
    • Timeline for removal
    • Migration examples
  4. Removal Timeline:
    • Pre-1.0.0: Deprecated features may be removed in the next MINOR version
    • Post-1.0.0: Deprecated features will be removed in the next MAJOR version (minimum 2 MINOR versions notice)

Example Deprecation Notice

import warnings

def old_function():
    warnings.warn(
        "old_function() is deprecated and will be removed in v1.0.0. "
        "Use new_function() instead.",
        DeprecationWarning,
        stacklevel=2
    )
    # ... implementation

Public API Boundaries

Stable Public APIs

These modules and their public exports are stable:

Core Metrics (fairpipe.metrics)

Pipeline (fairpipe.pipeline)

Integration (fairpipe.integration)

Training (fairpipe.training)

Monitoring (fairpipe.monitoring)

Exceptions (fairpipe.exceptions)

Internal APIs (Not Guaranteed)

The following are internal and may change without notice:

Recommendation: Import only from public modules listed in __init__.py files.

Configuration File Compatibility

Configuration Schema Evolution

Migration Strategy

Example: Configuration Evolution

v0.5.0 (previous):

pipeline:
  transformers:
    - type: InstanceReweighting
      sensitive: ["gender"]

v0.6.0 (hypothetical - adds optional field):

pipeline:
  transformers:
    - type: InstanceReweighting
      sensitive: ["gender"]
      # New optional field
      weight_threshold: 0.1

The v0.5.0 config remains valid in v0.6.0.

CLI Compatibility

Command Stability

Breaking Changes

If CLI changes are necessary:

  1. Deprecation warning issued in previous version
  2. Old command/argument remains functional for one MINOR version
  3. Migration guide provided
  4. Breaking change occurs in next MAJOR version

Data Format Compatibility

Input Formats

Output Formats

Python Version Support

Supported Python Versions

Dependency Compatibility

Migration Guides

When Migrating Between Versions

  1. Check CHANGELOG: Review CHANGELOG.md for breaking changes
  2. Review Migration Notes: Look for “Migration Notes” sections in release notes
  3. Test Incrementally: Test your code with the new version
  4. Update Dependencies: Ensure compatible dependency versions

Example Migration Scenarios

Scenario 1: MINOR Version Update (0.5.0 → 0.6.0)

Action: Update version, test existing code

Scenario 2: MAJOR Version Update (0.5.0 → 1.0.0)

Action: Review breaking changes, update code

Version Information

Checking Version

Programmatically:

from fairpipe import __version__
print(__version__)  # "0.6.2"

CLI:

fairpipe version
# Output: 0.6.2

Package Metadata:

pip show fairpipe

Release Process

Version Bumping

  1. PATCH: Bug fixes, security patches → increment PATCH
  2. MINOR: New features, enhancements → increment MINOR, reset PATCH
  3. MAJOR: Breaking changes → increment MAJOR, reset MINOR and PATCH

Release Checklist

See RELEASE.md for the mirror (SvrusIO/fAIr) and PyPI workflow.

Pre-1.0.0 Considerations

Current Status: Beta (0.6.2)

During the 0.x phase:

Path to 1.0.0

  1. API Stabilization: Finalize public API surface
  2. Documentation: Complete API documentation
  3. Testing: Comprehensive test coverage
  4. User Feedback: Incorporate feedback from beta users
  5. Breaking Changes: Address any remaining breaking changes before 1.0.0

Post-1.0.0

Once version 1.0.0 is released:

Best Practices for Users

Version Pinning

For Production:

fairpipe==0.6.2

For Development:

fairpipe>=0.6.2,<1.0.0

Staying Updated

  1. Subscribe to Releases: Watch GitHub repository for release notifications
  2. Review CHANGELOG: Check CHANGELOG.md before updating
  3. Test in Staging: Test new versions in non-production environments first
  4. Report Issues: Report compatibility issues via GitHub Issues

Avoiding Breaking Changes

Support and Questions

Reporting Compatibility Issues

If you encounter backward compatibility issues:

  1. Check Version: Verify you’re using a supported version
  2. Review CHANGELOG: Check if the issue is a known breaking change
  3. File Issue: Report on GitHub Issues
  4. Include Details: Version numbers, error messages, code examples

Getting Help

Summary

This policy ensures predictable, stable releases while allowing the toolkit to evolve and improve based on user needs and feedback.

This site is open source. Improve this page.