When evolving public APIs, prioritize backwards compatibility through proper deprecation strategies and careful interface design. Avoid breaking changes by using overloads, deprecation warnings, and gradual migration paths.

Key principles:

Example approach for adding new parameters:

def add_repository(
    self,
    repository: Repository,
    priority: Priority = Priority.PRIMARY,
    # Keep old parameters for backwards compatibility
    default: bool = False, 
    secondary: bool = False
) -> None:
    # Handle both old and new parameter styles
    if default or secondary:
        warnings.warn("default/secondary parameters are deprecated, use priority instead")

This ensures external code continues working while providing a clear upgrade path. Always weigh the benefits of cleaner APIs against the cost of breaking existing integrations.