Kindly Clarify Stability Policy

[Bibo-Joshi]

Hi.

As maintainer of a Bot API wrapper (python-telegram-bot.org), it's in my interest to ensure a stable interface for the users. For everything that passes data to the Bot API, I need to consider two cases:

1. Backward compatibility: Installing a verson of PTB that offers support for new Bot API changes shouldn't break existing code but offer a deprecation period).
   1. Removal of input class/method arguments in the Bot API. When keeping the field for a deprecation period, I need to know what to do with it: still pass it to TG and trust that it's handled correctly - or simply drop it as passing it to TG would cause an exception?
2. Forward compatibility: Running a version of PTB that does not yet offer support for new Bot API changes shouldn't break once the new Bot API changes go live
   1. Addition of new object fields is okay to handle, as I just need to filter out eveything that I don't have a native python representation for
   2. Addition of new method argumets is usually no problem either if they are optional. Addition of new required arguments is more tricky, since I usually don't want to immediately change the method signature but still signal to the user that the argument is now required.
   3. Removal of object fields. For optional fields also usually not a problem. For previously required fields, it is a problem. If these fields were to be removed without prior warning, I would have to basically handle all fields in the API specification as potentionally missing in the deserialization process.

So far, the Bot API has done a tremenduous job in ensuring compatibility between versions, shout out for that :)

Unfortunately, the information about only comes with the release notes themself which often contain hints such as "The field is still returned in the object for backward compatibility, but new bots should use the field sticker_type instead.". This makes it harder to implement the logic necessary for the stability as explained above beforehand - currently I'm mainly concerned aboit 2.iii here.

Hence my request

I would like to ask Telegram to document their Bot API stability policy on https://core.telegram.org/bots/api.
Please consider that being explicit about a stability policy can also be a benefit for maintaining the Bot API itself, as it allows to specify when deprecated functionality will actually be dropped such that legacy logic can be removed from the Bot API servers at some point rather than carrying it around for ever.

I'm looking forward to your reply :)

---

One could even go further and introduce api versioning, where e.g. making requests to api.telegram.org/v8/… is guaranteed to be backward compatible for the 8.x series, while switching to api.telegram.org/v9/… may contain breaking changes. And /v8 will be removed e.g. once /v10/ is there.
This would be an extremely large change though and I'm listing it mostly for completeness :D

[levlam]

Bot API handles all backward-compatibility itself. If you don't want to break backward compatibility while updating the library, then you can add new methods and fields, but also keep all removed fields and changed methods, only marking them as deprecated. All old code will continue to work subject to interaction of the bot with new features.

There are no reasons to ever remove backward compatibility from Bot API. API versioning only creates new issues without actually solving anything. You can't pretend that new features don't exist in v8 after v9 release.

[Bibo-Joshi]

Thank you for your swift reply. IMO it would be helpful to have this statement as official part of https://core.telegram.org/bots/api.

Could you kindly also comment on point 2.ii? I found one case in the very early days of the bot API that would have been relevant IISC:

https://core.telegram.org/bots/api-changelog#july-2015

The thumb field is now optional for Video, Sticker and Document objects

If a wrapper assumes that thumb is always present based on the description, then deserialization of these objects can fail once it's optional and can be missing. It would be good to have a citable statement on this as we're currently discussing about how we should handle this. ("Assume everything might be missing" vs "Assume that previously required fields will stay available even after they have been deprecated").

[levlam]

It is irrelevant to cite change logs from 2015th.

Could you kindly also comment on point 2.ii?

You can add the new method, but also keep the old method, only marking it as deprecated.

[Bibo-Joshi]

I realize I made a typo: I meant to ask about 2.iii, which is the scenario that the 2015 case matches. Please excuse my mistake.

It is irrelevant to cite change logs from 2015th.

I tend to disagree. Without an explicit confirmation about how such cases are handled, my best guess is to have a look at how it was handled previously. Yes, all later cases that I know of were handled differently. But this case is frankly enough to question the reliability of the handling.
My general point is: An API is a contract. If I can't know how the contracts terms change under new circumstances (but new circumstances are regularly expected), the contract is somewhat worthless :/

[levlam]

This was a fix of documentation error in 2015th. API wasn't changed.

[Bibo-Joshi]

I see, thanks for the clarification.
However, I note that you refrain from making an explicit statement about policies on deprecating objects fields 😉. I'll therefore have to go with "Assume everything might be missing".

---

As a side note: I'm aware that the Bot API is a free-to-use product and as a user I don't have any say in it's maintenance. OTOH the public TG APIs are clearly a community engagement tool meant to widen the user base and as such the profitability of TG. As such, I hope that you can understand my comments and questions (in this and previous threads) as feedback from the community that are intended to point out aspects of the Bot API that are uncomfortable to use/could be improved.

[levlam]

However, I note that you refrain from making an explicit statement about policies on deprecating objects fields 😉

I will not make impossible to enforce statements.

Also, see https://telegram.org/tos/bot-developers#9-1-unilateral-termination, which is the most precise statement that can be documented.