clock-curve-math 0.6.0

# Deprecation Policy - clock-curve-math

## Overview

This document outlines the deprecation policy for `clock-curve-math`. Since the 0.6.0 API is stable and no current deprecations are planned, this policy establishes procedures for future deprecations when they become necessary.

## When Deprecations Occur

Deprecations may be necessary for:

### Security Reasons

- APIs with security vulnerabilities
- Constant-time violations
- Cryptographic weaknesses

### API Design Improvements

- Inconsistent naming conventions
- Better abstractions available
- Simplified interfaces

### Maintenance Burden

- Complex internal implementations
- Difficult-to-maintain code
- Dependencies that need updating

### Ecosystem Evolution

- Better standards emerge
- New cryptographic primitives
- Improved algorithms

## Deprecation Process

### Phase 1: Deprecation Notice (T+0)

1. **Mark with `#[deprecated]`**: Add deprecation attribute with migration guidance
2. **Update Documentation**: Clearly document replacement APIs
3. **Release Notes**: Announce deprecation in changelog
4. **Migration Guide**: Provide detailed migration instructions

Example:

```rust
#[deprecated(
    since = "0.7.0",
    note = "Use `new_function()` instead. This function will be removed in 1.0.0"
)]
pub fn old_function() {
    // implementation
}
```

### Phase 2: Warning Period (T+1 Release)

1. **Compiler Warnings**: Users see deprecation warnings during compilation
2. **CI Compatibility**: CI systems may fail on deprecated usage
3. **Support Continues**: Deprecated APIs remain functional

### Phase 3: Removal (T+2 Major Release)

1. **Complete Removal**: Deprecated APIs removed from codebase
2. **Breaking Change**: Major version bump required
3. **Migration Required**: Users must update code

## Timeline Examples

### Example: Function Deprecation

```
0.7.0: Function marked deprecated
0.8.0: Still deprecated, warnings active
1.0.0: Function removed (BREAKING CHANGE)
```

### Example: Type Deprecation

```
0.7.0: Type marked deprecated
0.8.0: Still deprecated, migration path provided
1.0.0: Type removed (BREAKING CHANGE)
```

## Migration Support

### Automated Migration

- **Clippy Lints**: Custom lints for automated fixes
- **Migration Tools**: Scripts to update code automatically
- **IDE Integration**: Editor suggestions for replacements

### Documentation

- **Migration Guides**: Step-by-step upgrade instructions
- **Before/After Examples**: Code examples showing changes
- **Compatibility Matrix**: Feature compatibility across versions

### Support Channels

- **GitHub Issues**: Migration assistance requests
- **Documentation**: Comprehensive upgrade guides
- **Community Support**: Forums and discussion channels

## Current Status

### No Current Deprecations

As of version 0.6.0, no APIs are deprecated. The API is stable and well-designed.

### Future Considerations

Potential future deprecations may include:

1. **Naming Inconsistencies**: If any naming patterns prove problematic
2. **Performance**: APIs that become obsolete due to better implementations
3. **Security**: Any APIs found to have security issues
4. **Maintenance**: Complex APIs that become hard to maintain

## Deprecation Attributes

### Standard Format

```rust
#[deprecated(
    since = "x.y.z",
    note = "Use `new_api` instead. This will be removed in a.b.c"
)]
```

### Examples in Codebase

#### Function Deprecation

```rust
#[deprecated(
    since = "0.7.0",
    note = "Use `field::batch_inverse()` instead. This function will be removed in 1.0.0"
)]
pub fn old_batch_inverse_function() {
    // implementation
}
```

#### Type Deprecation

```rust
#[deprecated(
    since = "0.7.0",
    note = "Use `NewType` instead. This type will be removed in 1.0.0"
)]
pub struct OldType {
    // fields
}
```

#### Trait Deprecation

```rust
#[deprecated(
    since = "0.7.0",
    note = "Use `NewTrait` instead. This trait will be removed in 1.0.0"
)]
pub trait OldTrait {
    // methods
}
```

## Communication

### Release Notes

Each release will document:

- New deprecations introduced
- Deprecations scheduled for removal
- Migration timelines

### Changelog Format

```
## [0.7.0] - 2026-01-20

### Deprecated
- `old_function()` is deprecated, use `new_function()` instead
- `OldType` is deprecated, use `NewType` instead

### Removed
- None (first deprecation release)
```

## Tooling Support

### Clippy Integration

Custom Clippy lints will be developed for:

- Detecting deprecated API usage
- Suggesting automated fixes
- Providing migration guidance

### Build System Integration

- **Cargo Warnings**: Deprecation warnings in build output
- **CI Integration**: Optional failure on deprecated usage
- **Version Checking**: Tools to verify compatibility

## Exception Handling

### Emergency Removals

In cases of critical security issues:

- **Immediate Removal**: Security vulnerabilities may be removed without deprecation
- **Major Version Bump**: Always accompanied by major version change
- **Clear Communication**: Security advisory with migration guidance

### Ecosystem Impact

When deprecation affects multiple ecosystem crates:

- **Coordinated Release**: Timing with dependent crates
- **Extended Timeline**: Longer deprecation period for ecosystem impact
- **Migration Support**: Additional resources for ecosystem migration

## Version Compatibility

### Semantic Versioning Alignment

- **Patch (0.6.x)**: No deprecations or removals
- **Minor (0.7.0)**: Deprecations may be introduced
- **Major (1.0.0)**: Removals may occur

### LTS Considerations

For long-term support versions:

- **Extended Deprecation**: Longer warning periods
- **Backporting**: Critical fixes may be backported
- **Extended Support**: Longer maintenance windows

## Monitoring and Feedback

### Usage Metrics

- **Deprecation Warnings**: Track usage of deprecated APIs
- **Migration Progress**: Monitor ecosystem migration
- **Pain Points**: Identify difficult migrations

### Community Input

- **RFC Process**: Major deprecations may require RFC
- **Surveys**: Gather user feedback on proposed changes
- **Beta Testing**: Test migrations with beta releases

---

*This deprecation policy ensures smooth transitions and maintains ecosystem stability while allowing the library to evolve.*