JustAPI API Stability Guarantees

JustAPI's commitment to backward compatibility and stability.

Table of Contents

1. Versioning Policy
2. Stability Tiers
3. Breaking Changes
4. Deprecation Policy
5. Migration Support

1. Versioning Policy

JustAPI follows Semantic Versioning (SemVer):

• Major version (X.0.0): Breaking changes
• Minor version (0.X.0): New features, backward-compatible
• Patch version (0.0.X): Bug fixes, backward-compatible

Current Version

JustAPI is at v2.0.x (pre-1.0 stability guarantees apply).

Pre-1.0 Stability

Before v1.0.0, JustAPI may introduce breaking changes in minor versions. However: - Breaking changes will be documented in CHANGELOG.md - Migration guides will be provided - Deprecation warnings will be emitted before removal

2. Stability Tiers

Tier 1: Stable API

These APIs are guaranteed backward-compatible within major versions:

Tier 2: Experimental APIs

These APIs may change before v1.0:

Tier 3: Internal APIs

These are not part of the public API and may change without notice:

3. Breaking Changes

What Counts as Breaking

A breaking change is any modification that requires users to change their code:

• Removing or renaming a public function/class
• Changing function signatures
• Changing return types
• Changing exception types
• Changing default behavior

What Does NOT Count as Breaking

• Adding new optional parameters
• Adding new modules/classes
• Fixing bugs that change behavior to match documentation
• Performance improvements
• Security fixes

Breaking Change Process

1. Announce in GitHub Issues/Discussions
2. Document in CHANGELOG.md with migration guide
3. Deprecate old API with warnings (1 minor version)
4. Remove in next major version

4. Deprecation Policy

Deprecation Timeline

1. v0.X.0: Feature deprecated with warning
2. v0.X+1.0: Warning persists
3. v0.X+2.0: Feature removed

Deprecation Warnings

Deprecated APIs emit DeprecationWarning:

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

Finding Deprecated APIs

# Run with deprecation warnings enabled
python -W default::DeprecationWarning app.py

# Or filter specific warnings
python -W "default::DeprecationWarning:justapi" app.py

5. Migration Support

Migration Guides

JustAPI provides migration guides for common scenarios:

• From FastAPI
• From Robyn
• From Granian

Automated Migration Tools

# Check for deprecated APIs
justapi check --deprecated

# Generate migration suggestions
justapi migrate --from fastapi

Migration Support Timeline

6. Stability承诺

Our Commitment

JustAPI commits to:

1. No surprise breaking changes in minor/patch versions
2. 30-day notice before breaking changes
3. Migration guides for all breaking changes
4. LTS versions for production deployments
5. Security patches for all supported versions

Supported Versions

Getting Help

• Breaking change concerns: Open GitHub Issue
• Migration help: See migration guides
• Enterprise support: Contact maintainers