Documentation and deprecation notices for Options refactoring

[iMacTia]

Documentation and Deprecation Notices

Phase: 5 - Finalization
Release Target: v2.x.3
Tracking Issue: #1647
RFC: docs/options-detach-plan.md

Overview

Complete the Options refactoring with comprehensive documentation and any necessary deprecation notices. This ensures users understand the changes (even though they're backward compatible) and can adopt best practices.

Documentation Tasks

1. YARD Documentation

Add/update YARD comments for all new classes:

• Faraday::OptionsLike module

  • Purpose and usage
  • When to include this module
  • Duck-typing benefits

• Faraday::BaseOptions class

  • Abstract base class documentation
  • How subclasses should use it
  • MEMBERS and COERCIONS conventions
  • Example subclass implementation

• Updated Options subclass documentation:

  • ProxyOptions - document all attributes and methods
  • RequestOptions - document all attributes and methods
  • SSLOptions - document all attributes and methods
  • ConnectionOptions - document all attributes and methods
  • Env - emphasize hash-like access preservation

2. Changelog Updates

Update CHANGELOG.md with entries for each release:

v2.x.0:

### Internal Improvements
- Added `Faraday::OptionsLike` module for duck-typed Options compatibility
- Added `Faraday::BaseOptions` abstract base class
- Updated `Utils.deep_merge!` to support OptionsLike objects

v2.x.1:

### Internal Improvements
- Refactored `ProxyOptions`, `RequestOptions`, and `SSLOptions` to use `BaseOptions`
- No breaking changes - all existing APIs preserved

v2.x.2:

### Internal Improvements
- Refactored `ConnectionOptions` to use `BaseOptions`
- Improved nested options coercion
- No breaking changes - all existing APIs preserved

v2.x.3:

### Internal Improvements
- Refactored `Env` to use `BaseOptions` while preserving middleware hash-like access
- Completed Options architecture modernization
- No breaking changes - all existing APIs preserved
- Middleware and adapters continue to work unchanged

3. README Updates (if applicable)

• Review README.md for any Options-related content
• Update examples if they reference internal Options structure
• Ensure Options usage examples still work

4. Migration Guide (Optional)

Create docs/options-migration-guide.md (optional, for internal/advanced users):

# Options Architecture Migration Guide

This guide is for gem maintainers and advanced users who may have:
- Extended Faraday::Options in custom code
- Checked class inheritance with Options subclasses
- Used internal Options APIs

## What Changed

All Options subclasses now inherit from `BaseOptions` instead of `Options`.

## Public API - No Changes Needed

If you're using Options through public APIs, no changes needed:
- `Faraday.new(url, options)` - works unchanged
- `connection.request(options)` - works unchanged
- Middleware using `env[:key]` - works unchanged

## Advanced Usage - Possible Changes

If you have custom Options subclasses:
- Consider using `BaseOptions` instead of `Options`
- Include `OptionsLike` module for interop
- Define `MEMBERS` and `COERCIONS` constants

## Checking Compatibility

Use `is_a?(Faraday::OptionsLike)` instead of `is_a?(Faraday::Options)` 
for duck-typed Options checks.

5. Update .ai/guidelines.md

Add section about Options architecture:

## Options Architecture

Faraday uses an Options system for configuration:

### BaseOptions
- Abstract base class for all Options-like classes
- Subclasses define `MEMBERS` (array of attributes) and `COERCIONS` (hash of nested coercions)
- Provides `merge!`, `update`, `deep_dup`, `to_hash`, `.from` methods

### OptionsLike Module
- Marker interface for Options-like objects
- Used by `Utils.deep_merge!` for duck-typed compatibility

### Options Subclasses
- `ProxyOptions` - Proxy configuration
- `RequestOptions` - Request-level options (timeouts, params, etc.)
- `SSLOptions` - SSL/TLS configuration
- `ConnectionOptions` - Connection-level options
- `Env` - Request/response environment (preserves hash-like `[]`/`[]=` for middleware)

### Creating New Options Classes
When creating new Options-like classes:
1. Inherit from `BaseOptions`
2. Define `MEMBERS` constant (array of symbols)
3. Define `COERCIONS` constant (hash of attribute → class mappings)
4. Add `attr_accessor` for all members
5. Override `initialize` if custom logic needed

Deprecation Notices (Optional)

Options.memoized Macro

The RFC suggests potentially deprecating the .memoized macro from Options class (currently unused in new architecture).

Decision needed: Should we deprecate this?

If yes:

• Add deprecation warning to Options.memoized
• Document in changelog
• Plan removal for next major version

If no:

• Keep as-is for backward compatibility

Testing Documentation

• Ensure all code examples in documentation still work
• Test all YARD examples (if using @example tags)
• Verify links in documentation

Files to Create/Modify

Create:

• docs/options-migration-guide.md (optional)

Modify:

• CHANGELOG.md (4 release entries)
• README.md (if Options mentioned)
• .ai/guidelines.md (add Options architecture section)
• lib/faraday/options_like.rb (add YARD docs)
• lib/faraday/base_options.rb (add comprehensive YARD docs)
• lib/faraday/options/proxy_options.rb (add/update YARD docs)
• lib/faraday/options/request_options.rb (add/update YARD docs)
• lib/faraday/options/ssl_options.rb (add/update YARD docs)
• lib/faraday/options/connection_options.rb (add/update YARD docs)
• lib/faraday/options/env.rb (add/update YARD docs)
• lib/faraday/options.rb (deprecation notice if needed)

Acceptance Criteria

• All new classes have comprehensive YARD documentation
• Changelog updated for all 4 releases
• README reviewed and updated if needed
• .ai/guidelines.md includes Options architecture guidelines
• Migration guide created (if deemed necessary)
• All documentation examples tested and working
• Deprecation notices added (if applicable)

Dependencies

• Depends on: Convert Env to BaseOptions (preserve middleware API) #1653 (Env must be converted before documenting)
• Blocks: None (final task in refactoring)

Backward Compatibility

Documentation changes only - no code changes expected in this phase.

Communication Plan

After completing all releases:

• Consider blog post or announcement about architectural improvements
• Emphasize "no breaking changes" message
• Highlight improved maintainability
• Thank community for testing/feedback

Notes

• Keep documentation user-focused
• Emphasize backward compatibility throughout
• Internal architecture changes don't need prominent user-facing docs
• Focus on making migration guide helpful for advanced users

[iMacTia]

Dependencies: This issue depends on #1653 (all code changes must be complete before final documentation).

This is the final task in the refactoring - completing this closes out the entire Options architecture modernization! 🎉