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.
Enter the URL of a public GitHub repository