Tukukkk

I am maintaining a public API and have to deprecate a method.

Is there a general rule on how many months/years/versions before the deletion I should deprecate a method?

At minimum, you should keep deprecated methods in one version before removing them which seems kind of obvious when I write it out. I don't think there is a maximum time but if you never actually remove them, deprecation becomes a little pointless.

Major version releases are a good time to remove deprecated methods. Minor releases should typically not contain breaking changes.

This depends solely on what kind of stability guarantees you gave to your users, and how much pain you want to cause for your users.

Ideally, your API uses semver so that any breaking change causes the major version number to be incremented. In practice, it is desirable to do this almost never. If your API is installed via some package manager, you may want to create a new package name after a breaking change so that a simple upgrade doesn't cause conflicts (e.g. myapi2 v2.123.4 vs myapi3 v3.2.1). That may be unnecessary if your package manager supports tighter version dependencies (e.g. a dependency specification like ~v2.120 that does not include v3.*), but different package names have the advantage that incompatible versions can be used side by side very easily. Even when using semver, it can be sensible to have a deprecation period.

Semver is not always applicable. Then it is more important to communicate a clear stability policy. For example:

• Experimental features may be removed without notice.


• Features may be removed for security reasons at any time.


• Other features will only be removed
  
  
  
  
  • … after having been deprecated in a released version
  
  
  • … where that version is at least three months old
  
  
  • … and will be marked by a bump in the major version.
  
  
  
  

Such policies work particularly well when you have regular releases so that there is a clear deprecation period, e.g. one year.

Aside from marking any parts of the API as deprecated, you should make the deprecation widely known. For example:

• Have a section in your changelog about future directions and deprecations.


• Broadcast your intention to deprecate before you perform the deprecation, and listen into the community to see if there are substantial objections.


• Communicate what benefits will come from these changes. Depending on your user base, newsletters, presentations, blog posts, or press releases might be appropriate media. Having a spin “we are creating an awesome new feature! (which requires this widely used old feature to be removed)” is a bit less frustrating than removing a feature without context.

As for the exact deprecation period to choose, first look whether you have to honor any support contracts with your users. Such contracts may require you to maintain compatibility for some period. If not, consider any downstream impact. Try to change less rapidly than downstream users so that they can go through a deprecation cycle of their own. Downstream users will take some time to adapt to your changes, so you should never have a deprecation period shorter than a month.

First you should consider whether you want deprecated or obsolete.

Deprecated should be used for methods that are in some way harmful: security, performance, incorrect results. You want to get rid of them relatively quickly, no more than 2 major version and gone by the 3rd. For significant enough problems, deprecated may be deleted in the next minor version.

Obsolete is for things that are less useful for some reason, for instance returns less information or doesn’t work as well, doesn’t include as many options and so forth. These can hang around indefinitely, but should at a minimum be present in the next major version.