This page is an addition to the stability policy and is intended to be a helpful reference for the developers when working on Bot API updates that introudce backward incompatible changes.

A few cases can happen when Telegram makes changes to arguments of classes and methods. Here are a few hints on how these can be handled in a compatible way that is backward compatible or at least minimizes the impact of the change. Whether these hints are applied or the change is just implemented in a breaking way may be decided by the dev team on a case-by-case basis. This depends e.g. on the currently available capacity.

1. Optional arguments become mandatory

   1. Keep the argument optional in the method signature
   2. If the argument is not passed, raise a TypeError with a helpful message

   That way it's still a breaking change, but at least passed values are not randomly assigned to the wrong argument.

2. New positional argument is added and changes the order of the arguments

   1. Add it as optional argument
   2. If the argument is not passed, raise a TypeError with a helpful message

3. Optional argument is renamed

   1. Keep the old argument name in the method signature
   2. If the old argument is passed, issue a deprecation warning with a helpful message
   3. If both the old and the new argument are passed, raise a ValueError with a helpful message.

4. Mandatory argument is renamed / becomes optional

   1. Keep the old argument name in the method signature and make it optional
   2. If the old argument is passed, issue a deprecation warning with a helpful message
   3. If neither the old nor the new argument is passed, raise a TypeError with a helpful message
   4. If the old argument is not the first mandatory argument, make the ones before optional as well and raise a TypeError if they are not passed