Skip to content

BREAKINGS.md

Latest commit

 

History

History
630 lines (433 loc) · 15.6 KB

BREAKINGS.md

File metadata and controls

630 lines (433 loc) · 15.6 KB

Breaking Changes

This document outlines all breaking changes introduced in CTBase v0.18.0-beta compared to v0.17.4. Use this guide to migrate your code and understand the impact of these changes.

Table of Contents

Non-breaking note (0.18.7)

  • Version stabilization: Bumped from 0.18.6-beta to 0.18.7 for stable release. No functional changes; version promotion only.
  • Code formatting: Applied JuliaFormatter to ensure consistent code style across the codebase. No functional changes; formatting only.
  • CI improvements: Enhanced CompatHelper workflow with subdirs input for better dependency management. No functional changes; CI infrastructure only.
  • No breaking changes. No migration required.

Non-breaking note (0.18.6-beta)

  • Documenter Color Support: Added ANSI escape sequence support for exception display colors in generated documentation. Replaced printstyled calls with ANSI equivalents to enable automatic conversion to CSS classes by Documenter. No API changes; purely internal implementation improvement. No migration required.
  • Version bump to 0.18.6-beta for feature enhancement. No breaking changes. No migration required.

Non-breaking note (0.18.5)

  • Documentation reference fixes: removed unnecessary @ref macros from cross-references in docstrings across multiple modules and extensions. No API changes; purely documentation improvement. No migration required.
  • Version bump to 0.18.5 for maintenance release. No functional changes. No migration required.

Non-breaking note (0.18.4)

  • Test artifacts cleanup: removed test/extras/ and test/src/ directories containing demo scripts and temporary build artifacts. No API changes; purely repository hygiene. No migration required.
  • Enhanced TestRunner internal documentation with comprehensive docstrings for helper functions. No functional changes; documentation only. No migration required.

Non-breaking note (0.18.3-beta)

  • TestRunner progress bar now keeps full resolution up to 50 tests (previously 20) with cumulative coloring; compressed mode beyond 50 retains uniform bar. No breaking API change; purely visual behavior. No migration required.

Exception System Overhaul

🚨 Major Breaking Change

The entire exception system has been redesigned with enhanced types and richer context. While most existing exception types are preserved, their constructors and internal structure have changed.

Changed Exception Types

UnauthorizedCall → PreconditionError

# v0.17.4
throw(CTBase.UnauthorizedCall("message"))

# v0.18.0-beta  
throw(CTBase.PreconditionError("message"))

Enhanced Exception Constructors

All exceptions now support optional keyword arguments for enhanced context:

# v0.17.4
throw(CTBase.IncorrectArgument("message"))

# v0.18.0-beta (backward compatible)
throw(CTBase.IncorrectArgument("message"))

# v0.18.0-beta (enhanced version)
throw(CTBase.IncorrectArgument(
    "message";
    got="actual_value",
    expected="expected_value", 
    suggestion="how to fix",
    context="where it happened"
))

New Exception Fields

Exceptions now have additional fields that may affect code using reflection:

# v0.17.4
struct IncorrectArgument <: CTException
    var::String
end

# v0.18.0-beta
struct IncorrectArgument <: CTException
    msg::String
    got::Union{String, Nothing}
    expected::Union{String, Nothing}  
    suggestion::Union{String, Nothing}
    context::Union{String, Nothing}
end

Impact Assessment

  • Low Impact: Most existing throw calls will continue to work
  • Medium Impact: Code that inspects exception fields may need updates
  • High Impact: Code that specifically catches UnauthorizedCall needs updates

Module Reorganization

🚨 Structural Breaking Change

The monolithic source structure has been replaced with a modular architecture. This affects internal module organization but preserves the public API.

Before (v0.17.4)

# src/CTBase.jl
module CTBase
    # All code in single file or directly included
    include("exception.jl")
    include("description.jl") 
    include("default.jl")
    include("utils.jl")
end

After (v0.18.0-beta)

# src/CTBase.jl  
module CTBase
    # Modular organization
    include("Exceptions/Exceptions.jl")
    include("Core/Core.jl")
    include("Unicode/Unicode.jl") 
    include("Descriptions/Descriptions.jl")
    include("Extensions/Extensions.jl")
end

Internal Module Changes

New Internal Modules:

  • CTBase.Exceptions: Enhanced exception system
  • CTBase.Core: Fundamental types and utilities
  • CTBase.Unicode: Unicode character utilities
  • CTBase.Descriptions: Description management
  • CTBase.Extensions: Extension system

Impact Assessment - Module Reorganization

  • Low Impact: Public API remains unchanged
  • Medium Impact: Code accessing internal module structure may break
  • High Impact: Code that used using CTBase: InternalModule patterns

Extension System Introduction

🚨 New Extension Points

Several functions that previously had default implementations now require explicit extensions to be loaded.

Affected Functions

automatic_reference_documentation
# v0.17.4 - Had basic implementation
CTBase.automatic_reference_documentation()

# v0.18.0-beta - Requires extension
using CTBase.Extensions.DocumenterReference
CTBase.automatic_reference_documentation()
postprocess_coverage
# v0.17.4 - Had basic implementation
CTBase.postprocess_coverage()

# v0.18.0-beta - Requires extension
using CTBase.Extensions.CoveragePostprocessing  
CTBase.postprocess_coverage()
run_tests
# v0.17.4 - Had basic implementation
CTBase.run_tests()

# v0.18.0-beta - Requires extension  
using CTBase.Extensions.TestRunner
CTBase.run_tests()

Extension Error Handling

Attempting to use these functions without loading extensions now throws ExtensionError:

julia> CTBase.automatic_reference_documentation()
ERROR: ExtensionError. Please make: julia> using Documenter, Markdown, MarkdownAST

Impact Assessment - Extension System

  • Medium Impact: Code using these functions needs extension loading
  • Low Impact: Clear error messages guide users to solution
  • Documentation: All affected functions are well-documented

Documentation Generation Changes

🚨 Enhanced API Documentation System

The DocumenterReference extension has been significantly enhanced with new customization capabilities.

Title System Simplification

The API documentation title system has been standardized:

# v0.18.0-beta (variable titles)
# Different pages had inconsistent title patterns

# v0.18.0-beta.1 (standardized)
# All API pages consistently use:
# - "Public API" for exported functions
# - "Private API" for internal functions

New Customization Parameters

API documentation generation now supports customizable titles and descriptions:

# v0.18.0-beta (fixed titles)
automatic_reference_documentation()  # Used default titles

# v0.18.0-beta.1 (customizable)
automatic_reference_documentation(;
    public_title="Custom Public API",
    private_title="Internal Functions",
    public_description="Custom description for public API",
    private_description="Custom description for private API"
)

Impact Assessment - Documentation Changes

  • Low Impact: Existing code continues to work with defaults
  • Medium Impact: Code relying on specific title patterns may need updates
  • Enhancement: New customization provides better documentation control

API Changes

🚨 Public API Modifications

Exception Display Changes

Exception display formatting has changed significantly:

# v0.17.4
ERROR: IncorrectArgument: message

# v0.18.0-beta  
❌ IncorrectArgument: message

New Type Aliases

Some internal types have been formalized:

# v0.17.4 - Implicit usage
Tuple{Vararg{Symbol}}

# v0.18.0-beta - Explicit alias  
CTBase.DescVarArg

Unicode Module Organization

Unicode functions are now in a dedicated module:

# v0.17.4 - Direct access
CTBase.ctindice(1)

# v0.18.0-beta - Still works (re-exported)
CTBase.ctindice(1)

# v0.18.0-beta - Direct module access
CTBase.Unicode.ctindice(1)

TestRunner Enhancements

🚨 New Extension Features

The TestRunner extension has been significantly enhanced with advanced capabilities for test execution and progress tracking.

Progress Bar System Changes

The progress bar implementation has been completely rewritten with adaptive width:

# v0.18.0-beta (basic progress)
[████████████░░░░░░░░░░] ✓ [08/19] suite/exceptions/test_display.jl (2.5s)

# v0.18.0-beta.1 (adaptive width)
[████████░░░░░░░░░░] ✓ [08/19] suite/exceptions/test_display.jl (2.5s)
[████████████████████] ✓ [19/19] suite/exceptions/test_exceptions.jl (0.6s)

Enhanced Failure Detection

The failure detection mechanism is now more robust and accurate:

# v0.18.0-beta (unreliable)
# @test failures sometimes showed as success

# v0.18.0-beta.1 (robust detection)
# Correctly detects both exceptions and @test assertion failures

Path Prefix Stripping

Users can now use test/suite and suite interchangeably:

# v0.18.0-beta (explicit paths required)
julia --project -e 'using Pkg; Pkg.test(; test_args=["suite/exceptions"])'

# v0.18.0-beta.1 (automatic stripping)
julia --project -e 'using Pkg; Pkg.test(; test_args=["test/suite"])'  # Same result

Callback System Overhaul

The callback system has been enhanced with rich context information:

# v0.18.0-beta (basic callbacks)
on_test_done = info -> println("Done: $(info.status)")

# v0.18.0-beta.1 (rich context)
on_test_done = info -> begin
    if info.status == :error || info.status == :test_failed
        println("❌ FAILED: $(info.spec)")
    else
        println("✓ Success: $(info.spec)")
    end
end

Directory Protection

The system now prevents ambiguous directory structures:

# v0.18.0-beta (allowed)
test/
├── test/  # This would cause ambiguity with prefix stripping

# v0.18.0-beta.1 (protected)
ERROR: A subdirectory "test" exists inside the test directory

Test Path Handling Changes

Path prefix stripping behavior has been standardized:

# v0.18.0-beta (explicit paths required)
julia --project -e 'using Pkg; Pkg.test(; test_args=["suite/exceptions"])'

# v0.18.0-beta.1 (automatic stripping)
julia --project -e 'using Pkg; Pkg.test(; test_args=["test/suite"])'  # Same result

Note: The test/ prefix is now automatically stripped, making both forms equivalent.

📚 Documentation Improvements

Docstring Standards Compliance

All TestRunner functions now follow the project's documentation standards:

"""
$(TYPEDSIGNATURES)
Run tests with configurable file/function name builders...

# Arguments
- `args::AbstractVector{<:AbstractString}`: Command-line arguments...

Cross-Reference Resolution

All internal references now use fully qualified names to prevent header conflicts:

# v0.18.0-beta (conflicts)
See also: `TestRunInfo`  # Header conflicts

# v0.18.0-beta.1 (resolved)
See also: `TestRunner.TestRunInfo`

Dependency Updates

🚨 Version Requirements

Julia Version Increase

# v0.17.4
julia = "1.8"

# v0.18.0-beta  
julia = "1.10"

New Test Dependencies

# v0.18.0-beta additions
Aqua = "0.8"
OrderedCollections = "1"

Impact Assessment - Dependencies

  • Medium Impact: Projects on Julia < 1.10 cannot upgrade
  • Low Impact: New dependencies are test-only
  • Justification: Julia 1.10 provides better stability and performance

Migration Guide

📋 Step-by-Step Migration

1. Update Exception Handling

Find and replace UnauthorizedCall:

# In your codebase
find . -name "*.jl" -exec sed -i 's/UnauthorizedCall/PreconditionError/g' {} \;

Update exception field access:

# Before
catch e
    if e isa IncorrectArgument
        println(e.var)  # Direct field access
    end
end

# After  
catch e
    if e isa IncorrectArgument
        println(e.msg)  # Use new field name
    end
end

2. Load Required Extensions

Add extension loading to your code:

# For documentation generation
using CTBase
using CTBase.Extensions.DocumenterReference

# For test coverage
using CTBase  
using CTBase.Extensions.CoveragePostprocessing

# For advanced testing
using CTBase
using CTBase.Extensions.TestRunner

3. Update Julia Version

Update your project's compat requirements:

[compat]
julia = "1.10"

4. Test Your Migration

Run comprehensive tests:

using CTBase
using CTBase.Extensions.TestRunner

# Test all functionality
CTBase.run_tests()

🧪 Testing Migration

Exception Compatibility Test

function test_exception_migration()
    # Test old-style constructors still work
    e1 = CTBase.IncorrectArgument("test message")
    @test e1.msg == "test message"
    
    # Test new enhanced constructors
    e2 = CTBase.IncorrectArgument("test"; got="bad", expected="good")
    @test e2.got == "bad"
    @test e2.expected == "good"
end

Extension Loading Test

function test_extension_loading()
    # Test that extensions work
    using CTBase.Extensions.TestRunner
    @test_nowarn CTBase.run_tests(dry_run=true)
end

⚠️ Common Migration Issues

Issue 1: Missing Extensions

Problem: ExtensionError when using documentation functions

Solution:

# Add this to your code
using CTBase.Extensions.DocumenterReference

Issue 2: Exception Field Changes

Problem: Code accessing e.var on exceptions

Solution:

# Update field access
# Old: e.var  
# New: e.msg

Issue 3: Julia Version Compatibility

Problem: Project still on Julia 1.8/1.9

Solution:

# Update Julia
juliaup update 1.10

🔄 Backward Compatibility

What's Preserved

  • Public API: All public function signatures remain the same
  • Exception Types: All exception types still exist
  • Core Functionality: Description management, Unicode helpers work unchanged
  • Re-exports: Common functions remain available from CTBase

What's Changed

  • Exception Internals: Field structure and constructors enhanced
  • Module Organization: Internal structure modularized
  • Extension Points: Some functions now require explicit extensions
  • Error Messages: Enhanced formatting and context

Need Help?

📚 Resources

  • Documentation: Updated for v0.18.0-beta
  • Examples: See test/extras/ for migration examples
  • Issues: Report migration problems on GitHub
  • Discussions: Ask questions in GitHub Discussions

🤝 Support

If you encounter migration issues:

  1. Check this guide for common solutions
  2. Run the test suite to identify specific problems
  3. Open an issue with minimal reproduction
  4. Join discussions for community support

This breaking changes guide is comprehensive but not exhaustive. Test your migration thoroughly and report any undocumented issues.