cognitive/docs/api/api_versioning.md

API Versioning Guidelines

---

title: API Versioning Guidelines type: guide status: stable created: 2024-02-06 tags:

• api
• versioning
• guidelines
• compatibility semantic_relations:
• type: implements links: api_documentation
• type: relates links:
  • documentation_standards
  • package_documentation

---

Overview

This guide establishes versioning standards for the Cognitive Modeling Framework's API, ensuring compatibility and clear upgrade paths. See api_documentation for general API documentation guidelines.

Version Structure

Semantic Versioning

# @version_format
version_format = {
    "major": "Breaking changes",          # e.g., 2.0.0
    "minor": "New features",              # e.g., 1.1.0
    "patch": "Bug fixes",                 # e.g., 1.0.1
    "pre_release": "Alpha/Beta/RC",       # e.g., 1.0.0-alpha.1
    "build": "Build metadata"             # e.g., 1.0.0+build.123
}

Version Rules

# @version_rules
versioning_rules = {
    "major_change": {
        "triggers": [
            "Breaking API changes",
            "Incompatible behavior changes",
            "Major architectural changes"
        ],
        "requirements": [
            "Migration guide",
            "Deprecation notices",
            "Compatibility layer"
        ]
    },
    "minor_change": {
        "triggers": [
            "New features",
            "Non-breaking additions",
            "Optional capabilities"
        ],
        "requirements": [
            "Feature documentation",
            "Example updates",
            "Test coverage"
        ]
    },
    "patch_change": {
        "triggers": [
            "Bug fixes",
            "Performance improvements",
            "Documentation updates"
        ],
        "requirements": [
            "Change documentation",
            "Test cases",
            "Regression tests"
        ]
    }
}

API Changes

Breaking Changes

Changes that require a major version increment:

# Before (1.0.0)
def update_beliefs(self, observation: np.ndarray) -> np.ndarray:
    """Update agent beliefs."""
    pass

# After (2.0.0)
def update_beliefs(self, 
                  observation: np.ndarray,
                  precision: float) -> Tuple[np.ndarray, float]:
    """
    Update agent beliefs with precision.
    See [[belief_updating]] for details.
    """
    pass

Non-Breaking Additions

Changes that require a minor version increment:

# Original (1.0.0)
class ActiveInferenceAgent:
    def __init__(self):
        pass

# Addition (1.1.0)
class ActiveInferenceAgent:
    def __init__(self):
        pass
        
    def save_state(self) -> dict:
        """
        New method for state serialization.
        See [[state_management]] for details.
        """
        pass

Patch Changes

Changes that require a patch version increment:

# Bug fix (1.0.1)
def compute_free_energy(beliefs: np.ndarray) -> float:
    """
    Fixed numerical stability issue.
    See [[numerical_stability]] for details.
    """
    # Fixed implementation
    pass

Deprecation Process

Deprecation Timeline

# @deprecation_timeline
deprecation_process = {
    "announcement": {
        "timing": "One major version before removal",
        "requirements": ["Documentation", "Migration guide"]
    },
    "warning_phase": {
        "duration": "One minor version cycle",
        "actions": ["Runtime warnings", "Documentation notices"]
    },
    "removal": {
        "timing": "Next major version",
        "requirements": ["Breaking change notice", "Alternative documentation"]
    }
}

Deprecation Notices

# Example deprecation warning
def old_method(self):
    """
    Deprecated: Will be removed in 2.0.0.
    Use new_method() instead.
    See [[migration_guide]] for details.
    """
    warnings.warn(
        "old_method is deprecated and will be removed in 2.0.0. "
        "Use new_method instead.",
        DeprecationWarning,
        stacklevel=2
    )

Version Management

Version Tracking

# @version_tracking
version_info = {
    "documentation": {
        "current_version": "[[api_reference]]",
        "previous_versions": "[[api_archive]]",
        "migration_guides": "[[migration_guide]]"
    },
    "compatibility": {
        "python_versions": "[[python_compatibility]]",
        "dependencies": "[[dependency_matrix]]",
        "platforms": "[[platform_support]]"
    }
}

Release Process

1. Version Bump

   # Update version
   __version__ = "1.1.0"
   

2. Documentation Update

   • Update api_reference
   • Update changelog
   • Update migration_guide

3. Validation

   • Run validation_framework
   • Check compatibility_matrix
   • Verify documentation_completeness

Compatibility

Python Version Support

# @python_support
python_versions = {
    "minimum": "3.8",
    "recommended": "3.9+",
    "tested": ["3.8", "3.9", "3.10"]
}

Dependency Management

# @dependency_management
dependency_rules = {
    "core": {
        "numpy": ">=1.20.0",
        "scipy": ">=1.7.0"
    },
    "optional": {
        "visualization": {
            "matplotlib": ">=3.4.0"
        },
        "optimization": {
            "torch": ">=1.9.0"
        }
    }
}

Documentation Requirements

Version Documentation

Each version requires:

• Complete api_reference
• Updated example_writing
• changelog entries
• migration_guide (if needed)

Compatibility Documentation

• dependency_matrix
• platform_support
• python_compatibility
• integration_guide

Best Practices

1. Version Control

• Use semantic versioning
• Document all changes
• Maintain changelog
• Provide migration guides

2. Compatibility

• Check dependency impacts
• Test all supported versions
• Document requirements
• Verify integrations

3. Documentation

• Update all affected docs
• Provide upgrade guides
• Include examples
• Verify completeness

Related Documentation

• api_documentation
• package_documentation
• documentation_standards
• validation_framework

References

• versioning_standards
• compatibility_guide
• migration_patterns
• documentation_tools