API Migration: Transition to Configuration Object API for GitHub Operations

[ali90h]

Overview

Issue #38 introduced a new configuration object-based API for GitHub operations that reduces parameter complexity while maintaining full backward compatibility. This ticket serves as a reminder to gradually migrate to the new API and establish guidelines for when to replace the old API.

New API Available

The following functions now support configuration object-based APIs:

• upsert_pr_comment() - accepts CommentOperationRequest
• upsert_issue_comment() - accepts CommentOperationRequest
• generate_plan_for_issue() - accepts PlanGenerationRequest

When to Use New API vs Old API

✅ Use New API When:

1. Writing new code - All new functions should use config objects
2. Complex parameter combinations - When you need to pass 4+ parameters
3. Repeated similar calls - Config objects can be reused across multiple calls
4. Unit testing - Config objects make test setup cleaner and more readable
5. Adding new features - New functionality should adopt the modern API patterns
6. Refactoring existing functions - When touching old code, consider upgrading

🔄 Keep Old API When:

1. Simple, one-off calls - For basic operations with 1-2 parameters
2. Legacy code that works - Don't change working code unless adding features
3. External integrations - If other tools depend on current function signatures
4. Performance-critical paths - Old API has slightly less object allocation overhead

Migration Strategy

Phase 1: New Code Only (Current)

• All new functions should use configuration object API
• Leave existing working code unchanged
• Document new API patterns in developer guidelines

Phase 2: Gradual Migration (Future)

Trigger conditions for migration:

• When adding new parameters to existing functions
• When fixing bugs in parameter handling
• When refactoring modules for other reasons
• During major version releases

Phase 3: Deprecation (Far Future)

• Add deprecation warnings to old API (not before v2.0.0)
• Provide migration tools/scripts
• Full removal only in major version bump

Implementation Guidelines

For New Code:

# ✅ Recommended - New API
config = GitHubOperationConfig(
    gh_path="gh",
    dry_run=False, 
    replace_block=True
)
request = CommentOperationRequest(
    target_id=pr_number,
    body=comment_body,
    config=config
)
upsert_pr_comment(request)

# ❌ Avoid for new code - Old API  
upsert_pr_comment(pr_number, comment_body, replace_block=True, gh_path="gh", dry_run=False)

For Existing Code:

# ✅ Leave as-is if working
upsert_pr_comment(123, "body", dry_run=True)  # Don't change working code

# ✅ Upgrade when adding features
# If you need to add new parameters or modify behavior, consider upgrading to new API

Benefits of New API

• Reduced parameter complexity - Group related parameters logically
• Better type safety - Full dataclass validation and type checking
• Enhanced extensibility - Easy to add new configuration options
• Improved testing - Config objects are easier to mock and validate
• Better IDE support - Auto-completion for configuration parameters
• Cleaner code - Self-documenting parameter groups

Action Items

• Update developer documentation with API guidelines
• Create examples showing both APIs in README
• Add new API usage to code review checklist
• Consider new API when working on any GitHub operation functions
• Monitor usage patterns and gather feedback

Timeline

• Immediate: Use new API for all new GitHub operation code
• Next 6 months: Gradually migrate high-touch functions when making other changes
• Next year: Evaluate usage patterns and consider deprecation timeline
• Future major version: Potentially deprecate old API (with plenty of notice)

Related

• Closes Reduce Function Parameter Count (PLR0913) #38 - Original parameter count reduction issue
• Configuration objects: autorepro/config/github_ops.py
• Refactored functions: autorepro/pr.py, autorepro/issue.py

---

Note: This is a reminder/planning ticket. No immediate action required - both APIs work perfectly. Use this as guidance for future development decisions.