I felt like an issue is the proper place to discuss this, since we are going to make some decisions on how to handle API updates from now on which are bigger then simple doc behavior.

Hinrich suggested the following list of points to be included in the contributing guide, where we need to standardize our approach:

• deprecated optional arguments
• deprecated positional arguments
• new positional arguments that change the order
• deprecated attributes
• equality comparison
• issuing deprecation warnings
• handling api_kwargs
• clarifying how long deprecated functionality will still be available
• to_dict
• maybe more

deprecated optional/positional arguments/attributes

I would warn a DeprecationWarning, and remove the old ones in the next major version.

new positional arguments that change the order

I think here its enough to mention in the version string, people should name their arguments or expect to have issues.

equality comparison

I would add the new stuff, an object without it is different then one with

That's is all I feel comfortable commenting about right now.