8000 Add a Stability Policy (#3622) · Devors/python-telegram-bot@1c6ae43 · GitHub
[go: up one dir, main page]
Skip to content

Commit 1c6ae43

Browse files
Bibo-JoshiPoolitzerharshil21lemontree210
authored
Add a Stability Policy (python-telegram-bot#3622)
Co-authored-by: poolitzer <github@poolitzer.eu> Co-authored-by: Harshil <37377066+harshil21@users.noreply.github.com> Co-authored-by: Dmitry Kolomatskiy <58207913+lemontree210@users.noreply.github.com>
1 parent 66b6d3c commit 1c6ae43

File tree

9 files changed

+218
-43
lines changed

9 files changed

+218
-43
lines changed

‎.github/CONTRIBUTING.rst

Lines changed: 51 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -67,6 +67,7 @@ Here's how to make a one-off code change.
6767
$ git checkout -b your-branch-name
6868
6969
3. **Make a commit to your feature branch**. Each commit should be self-contained and have a descriptive commit message that helps other developers understand why the changes were made.
70+
We also have a check-list for PRs `below`_.
7071

7172
- You can refer to relevant issues in the commit message by writing, e.g., "#105".
7273

@@ -80,7 +81,7 @@ Here's how to make a one-off code change.
8081

8182
- The following exceptions to the above (Google's) style guides applies:
8283

83-
- Documenting types of global variables and complex types of class members can be done using the Sphinx docstring convention.
84+
- Documenting types of global variables and complex types of class members can be done using the Sphinx docstring convention.
8485

8586
- In addition, PTB uses some formatting/styling and linting tools in the pre-commit setup. Some of those tools also have command line tools that can help to run these tools outside of the pre-commit step. If you'd like to leverage that, please have a look at the `pre-commit config file`_ for an overview of which tools (and which versions of them) are used. For example, we use `Black`_ for code formatting. Plugins for Black exist for some `popular editors`_. You can use those instead of manually formatting everything.
8687

@@ -121,11 +122,11 @@ Here's how to make a one-off code change.
121122

122123
- When your reviewer has reviewed the code, you'll get a notification. You'll need to respond in two ways:
123124

124-
- Make a new commit addressing the comments you agree with, and push it to the same branch. Ideally, the commit message would explain what the commit does (e.g. "Fix lint error"), but if there are lots of disparate review comments, it's fine to refer to the original commit message and add something like "(address review comments)".
125+
- Make a new commit addressing the comments you agree with, and push it to the same branch. Ideally, the commit message would explain what the commit does (e.g. "Fix lint error"), but if there are lots of disparate review comments, it's fine to refer to the original commit message and add something like "(address review comments)".
125126

126-
- In order to keep the commit history intact, please avoid squashing or amending history and then force-pushing to the PR. Reviewers often want to look at individual commits.
127+
- In order to keep the commit history intact, please avoid squashing or amending history and then force-pushing to the PR. Reviewers often want to look at individual commits.
127128

128-
- In addition, please reply to each comment. Each reply should be either "Done" or a response explaining why the corresponding suggestion wasn't implemented. All comments must be resolved before LGTM can be given.
129+
- In addition, please reply to each comment. Each reply should be either "Done" or a response explaining why the corresponding suggestion wasn't implemented. All comments must be resolved before LGTM can be given.
129130

130131
- Resolve any merge conflicts that arise. To resolve conflicts between 'your-branch-name' (in your fork) and 'master' (in the ``python-telegram-bot`` repository), run:
131132

@@ -150,6 +151,51 @@ Here's how to make a one-off code change.
150151
151152
7. **Celebrate.** Congratulations, you have contributed to ``python-telegram-bot``!
152153

154+
Check-list for PRs
155+
------------------
156+
157+
This checklist is a non-exhaustive reminder of things that should be done before a PR is merged, both for you as contributor and for the maintainers.
158+
Feel free to copy (parts of) the checklist to the PR description to remind you or the maintainers of open points or if you have questions on anything.
159+
160+
- Added ``.. versionadded:: NEXT.VERSION``, ``.. versionchanged:: NEXT.VERSION`` or ``.. deprecated:: NEXT.VERSION`` to the docstrings for user facing changes (for methods/class descriptions, arguments and attributes)
161+
- Created new or adapted existing unit tests
162+
- Documented code changes according to the `CSI standard <https://standards.mousepawmedia.com/en/stable/csi.html>`__
163+
- Added myself alphabetically to ``AUTHORS.rst`` (optional)
164+
- Added new classes & modules to the docs and all suitable ``__all__`` s
165+
- Checked the `Stability Policy <https://docs.python-telegram-bot.org/stability_policy.html>`_ in case of deprecations or changes to documented behavior
166+
167+
**If the PR contains API changes (otherwise, you can ignore this passage)**
168+
169+
- Checked the Bot API specific sections of the `Stability Policy <https://docs.python-telegram-bot.org/stability_policy.html>`_
170+
171+
- New classes:
172+
173+
- Added ``self._id_attrs`` and corresponding documentation
174+
- ``__init__`` accepts ``api_kwargs`` as kw-only
175+
176+
- Added new shortcuts:
177+
178+
- In :class:`~telegram.Chat` & :class:`~telegram.User` for all methods that accept ``chat/user_id``
179+
- In :class:`~telegram.Message` for all methods that accept ``chat_id`` and ``message_id``
180+
- For new :class:`~telegram.Message` shortcuts: Added ``quote`` argument if methods accepts ``reply_to_message_id``
181+
- In :class:`~telegram.CallbackQuery` for all methods that accept either ``chat_id`` and ``message_id`` or ``inline_message_id``
182+
183+
- If relevant:
184+
185+
- Added new constants at :mod:`telegram.constants` and shortcuts to them as class variables
186+
- Link new and existing constants in docstrings instead of hard-coded numbers and strings
187+
- Add new message types to :attr:`telegram.Message.effective_attachment`
188+
- Added new handlers for new update types
189+
190+
- Add the handlers to the warning loop in the :class:`~telegram.ext.ConversationHandler`
191+
192+
- Added new filters for new message (sub)types
193+
- Added or updated documentation for the changed class(es) and/or method(s)
194+
- Added the new method(s) to ``_extbot.py``
195+
- Added or updated ``bot_methods.rst``
196+
- Updated the Bot API version number in all places: ``README.rst`` and ``README_RAW.rst`` (including the badge), as well as ``telegram.constants.BOT_API_VERSION_INFO``
197+
- Added logic for arbitrary callback data in :class:`telegram.ext.ExtBot` for new methods that either accept a ``reply_markup`` in some form or have a return type that is/contains :class:`~telegram.Message`
198+
153199
Documenting
154200
===========
155201

@@ -266,3 +312,4 @@ break the API classes. For example:
266312
.. _`CSI`: https://standards.mousepawmedia.com/en/stable/csi.html
267313
.. _`section`: #documenting
268314
.. _`testing page`: https://github.com/python-telegram-bot/python-telegram-bot/blob/master/tests/README.rst
315+
.. _`below`: #check-list-for-prs

‎.github/pull_request_template.md

Lines changed: 3 additions & 35 deletions
Original file line numberDiff line numberDiff line change
@@ -1,38 +1,6 @@
11
<!--
2-
Hey! You're PRing? Cool! Please have a look at the below checklist. It's here to help both you and the maintainers to remember some aspects. Make sure to check out our contribution guide (https://github.com/python-telegram-bot/python-telegram-bot/blob/master/.github/CONTRIBUTING.rst).
2+
Hey! You're PRing? Cool!
3+
Please be sure to check out our contribution guide (https://github.com/python-telegram-bot/python-telegram-bot/blob/master/.github/CONTRIBUTING.rst).
4+
Especially, please have a look at the check list for PRs (https://github.com/python-telegram-bot/python-telegram-bot/blob/master/.github/CONTRIBUTING.rst#checklist-for-prs). Feel free to copy (parts of) the checklist to the PR description to remind you or the maintainers of open points or if you have questions on anything.
35
-->
46

5-
### Checklist for PRs
6-
7-
- [ ] Added `.. versionadded:: version`, `.. versionchanged:: version` or `.. deprecated:: version` to the docstrings for user facing changes (for methods/class descriptions, arguments and attributes)
8-
- [ ] Created new or adapted existing unit tests
9-
- [ ] Documented code changes according to the [CSI standard](https://standards.mousepawmedia.com/en/stable/csi.html)
10-
- [ ] Added myself alphabetically to `AUTHORS.rst` (optional)
11-
- [ ] Added new classes & modules to the docs and all suitable `__all__` s
12-
13-
14-
### If the PR contains API changes (otherwise, you can delete this passage)
15-
16-
* New classes:
17-
- [ ] Added `self._id_attrs` and corresponding documentation
18-
- [ ] `__init__` accepts `api_kwargs` as kw-only
19-
20-
* Added new shortcuts:
21-
- [ ] In `Chat` & `User` for all methods that accept `chat/user_id`
22-
- [ ] In `Message` for all methods that accept `chat_id` and `message_id`
23-
- [ ] For new `Message` shortcuts: Added `quote` argument if methods accepts `reply_to_message_id`
24-
- [ ] In `CallbackQuery` for all methods that accept either `chat_id` and `message_id` or `inline_message_id`
25-
26-
* If relevant:
27-
28-
- [ ] Added new constants at `telegram.constants` and shortcuts to them as class variables
29-
- [ ] Link new and existing constants in docstrings instead of hard coded number and strings
30-
- [ ] Add new message types to `Message.effective_attachment`
31-
- [ ] Added new handlers for new update types
32-
- [ ] Add the handlers to the warning loop in the `ConversationHandler`
33-
- [ ] Added new filters for new message (sub)types
34-
- [ ] Added or updated documentation for the changed class(es) and/or method(s)
35-
- [ ] Added the new method(s) to `_extbot.py`
36-
- [ ] Added or updated `bot_methods.rst`
37-
- [ ] Updated the Bot API version number in all places: `README.rst` and `README_RAW.rst` (including the badge), as well as `telegram.constants.BOT_API_VERSION_INFO`
38-
- [ ] Added logic for arbitrary callback data in `tg.ext.Bot` for new methods that either accept a `reply_markup` in some form or have a return type that is/contains `telegram.Message`

‎CHANGES.rst

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,5 @@
1+
.. _ptb-changelog:
2+
13
=========
24
Changelog
35
=========

‎docs/source/examples.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@ aspect of the Telegram Bot API while others focus on one of the
88
mechanics of this library. Except for the
99
:any:`examples.rawapibot` example, they all use the high-level
1010
framework this library provides with the
11-
:any:`telegram.ext <telegram.ext>` submodule.
11+
:mod:`telegram.ext` submodule.
1212

1313
All examples are licensed under the `CC0
1414
License <https://github.com/python-telegram-bot/python-telegram-bot/blob/master/examples/LICENSE.txt>`__

‎docs/source/index.rst

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -27,11 +27,12 @@
2727
:hidden:
2828
:caption: Project
2929

30+
stability_policy
3031
changelog
32+
coc
33+
contributing
34+
testing
3135
Website <https://python-telegram-bot.org>
3236
GitHub Repository <https://github.com/python-telegram-bot/python-telegram-bot/>
3337
Telegram Channel <https://t.me/pythontelegrambotchannel/>
3438
Telegram User Group <https://t.me/pythontelegrambotgroup/>
35-
coc
36-
contributing
37-
testing

‎docs/source/stability_policy.rst

Lines changed: 143 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,143 @@
1+
Stability Policy
2+
================
3+
4+
.. important::
5+
6+
This stability policy is in place since version NEXT.VERSION.
7+
While earlier versions of ``python-telegram-bot`` also had stable interfaces, they had no explicit stability policy and hence did not follow the rules outlined below in all detail.
8+
Please also refer to the :ref:`changelog <ptb-changelog>`.
9+
10+
.. caution::
11+
12+
Large parts of the :mod:`telegram` package are the Python representations of the Telegram Bot API, whose stability policy PTB can not influence.
13+
This policy hence includes some special cases for those parts.
14+
15+
What does this policy cover?
16+
----------------------------
17+
18+
This policy includes any API or behavior that is covered in this documentation.
19+
This covers both the :mod:`telegram` package and the :mod:`telegram.ext` package.
20+
21+
What doesn't this policy cover?
22+
-------------------------------
23+
24+
Introduction of new features or changes of flavors of comparable behavior (e.g. the default for the HTTP protocol version being used) are not covered by this policy.
25+
26+
The internal structure of classes in PTB, i.e. things like the result of ``dir(obj))`` or the contents of ``obj.__dict__``, is not covered by this policy.
27+
28+
Objects are in general not guaranteed to be pickleable (unless stated otherwise) and pickled objects from one version of PTB may not be loadable in future versions.
29+
We may provide a way to convert pickled objects from one version to another, but this is not guaranteed.
30+
31+
Functionality that is part of PTBs API but is explicitly documented as not being intended to be used directly by users (e.g. :meth:`telegram.request.BaseRequest.do_request`) may change.
32+
This also applies to functions or attributes marked as final in the sense of `PEP 591 <https://www.python.org/dev/peps/pep-0591/>`__.
33+
34+
PTB has dependencies to third-party packages.
35+
The versions that PTB uses of these third-party packages may change if that does not affect PTBs public API.
36+
37+
PTB does not give guarantees about which Python versions are supported.
38+
In general, we will try to support all Python versions that have not yet reached their end of life, but we reserve ourselves the option to drop support for Python versions earlier if that benefits the advancement of the library.
39+
40+
.. _bot-api-functionality-1:
41+
42+
Bot API Functionality
43+
~~~~~~~~~~~~~~~~~~~~~
44+
45+
Comparison of equality of instances of the classes in the :mod:`telegram` package is subject to change and the PTB team will update the behavior to best reflect updates in the Bot API.
46+
Changes in this regard will be documented in the affected classes.
47+
Note that equality comparison with objects that where serialized by an older version of PTB may hence give unexpected results.
48+
49+
When the order of arguments of the Bot API methods changes or they become optional/mandatory due to changes in the Bot API, PTB will always try to reflect these changes.
50+
While we try to make such changes backward compatible, this is not always possible or only with significant effort.
51+
In such cases we will find a trade-off between backward compatibility and fully complying with the Bot API, which may result in breaking changes.
52+
We highly recommend using keyword arguments, which can help make such changes non-breaking on your end.
53+
54+
..
55+
We have documented a few common cases and possible backwards compatible solutions in the wiki as a reference for the dev team: https://github.com/python-telegram-bot/python-telegram-bot/wiki/Bot-API-Backward-Compatibility
56+
57+
When the Bot API changes attributes of classes, the method :meth:`telegram.TelegramObject.to_dict` will change as necessary to reflect these changes.
58+
In particular, attributes deprecated by Telegram will be removed from the returned dictionary.
59+
Deprecated attributes that are still passed by Telegram will be available in the :attr:`~telegram.TelegramObject.api_kwargs` dictionary as long as PTB can support that with feasible effort.
60+
Since attributes of the classes in the :mod:`telegram` package are not writable, we may change them to properties where appropriate.
61+
62+
Development Versions
63+
~~~~~~~~~~~~~~~~~~~~
64+
65+
Pre-releases marked as alpha, beta or release candidate are not covered by this policy.
66+
Before a feature is in a stable release, i.e. the feature was merged into the ``master`` branch but not released yet (or only in a pre-release), it is not covered by this policy either and may change.
67+
68+
Security
69+
~~~~~~~~
70+
71+
We make exceptions from our stability policy for security.
72+
We will violate this policy as necessary in order to resolve a security issue or harden PTB against a possible attack.
73+
74+
Versioning
75+
----------
76+
77+
PTB uses a versioning scheme that roughly follows `https://semver.org/ <https://semver.org/>`_, although it may not be quite as strict.
78+
79+
Given a version of PTB X.Y.Z,
80+
81+
- X indicates the major version number.
82+
This is incremented when backward incompatible changes are introduced.
83+
- Y indicates the minor version number.
84+
This is incremented when new functionality or backward compatible changes are introduced by PTB.
85+
*This is also incremented when PTB adds support for a new Bot API version, which may include backward incompatible changes in some cases as outlined* :ref:`below <bot-api-versioning>`.
86+
- Z is the patch version.
87+
This is incremented if backward compatible bug fixes or smaller changes are introduced.
88+
If this number is 0, it can be omitted, i.e. we just write X.Y instead of X.Y.0.
89+
90+
Deprecation
91+
~~~~~~~~~~~
92+
93+
From time to time we will want to change the behavior of an API or remove it entirely, or we do so to comply with changes in the Telegram Bot API.
94+
In those cases, we follow a deprecation schedule as detailed below.
95+
96+
Functionality is marked as deprecated by a corresponding note in the release notes and the documentation.
97+
Where possible, a :class:`~telegram.warnings.PTBDeprecationWarning` is issued when deprecated functionality is used, but this is not mandatory.
98+
99+
From time to time, we may decide to deprecate an API that is particularly widely used.
100+
In these cases, we may decide to provide an extended deprecation period, at our discretion.
101+
102+
With version 20.0.0, PTB introduced major structural breaking changes without the above deprecation period.
103+
Should a similarly big change ever be deemed necessary again by the development team and should a deprecation period prove too much additional effort, this violation of the stability policy will be announced well ahead of the release in our channel, `as was done for v20 <https://t.me/pythontelegrambotchannel/94>`_.
104+
105+
Non-Bot API Functionality
106+
#########################
107+
108+
Starting with version NEXT.VERSION, deprecated functionality will stay available for the current and the next major version.
109+
For example:
110+
111+
- In PTB v20.1.1 the feature exists
112+
- In PTB v20.1.2 or v20.2.0 the feature is marked as deprecated
113+
- In PTB v21.*.* the feature is marked as deprecated
114+
- In PTB v22.0 the feature is removed or changed
115+
116+
.. _bot-api-versioning:
117+
118+
Bot API Functionality
119+
#####################
120+
121+
As PTB has no control over deprecations introduced by Telegram and the schedule of these deprecations rarely coincides with PTBs deprecation schedule, we have a special policy for Bot API functionality.
122+
123+
Starting with NEXT.VERSION, deprecated Bot API functionality will stay available for the current and the next major version of PTB *or* until the next version of the Bot API.
124+
More precisely, two cases are possible, for which we show examples below.
125+
126+
Case 1
127+
^^^^^^
128+
129+
- In PTB v20.1 the feature exists
130+
- Bot API version 6.6 is released and deprecates the feature
131+
- PTB v20.2 adds support for Bot API 6.6 and the feature is
132+
marked as deprecated
133+
- In PTB v21.0 the feature is removed or changed
134+
135+
Case 2
136+
^^^^^^
137+
138+
- In PTB v20.1 the feature exists
139+
- Bot API version 6.6 is released and deprecates the feature
140+
- PTB v20.2 adds support for Bot API version 6.6 and the feature is marked as deprecated
141+
- In PTB v20.2.* and v20.3.* the feature is marked as deprecated
142+
- Bot API version 6.7 is released
143+
- PTB v20.4 adds support for Bot API version 6.7 and the feature is removed or changed

‎docs/source/telegram.ext.rst

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,8 @@
11
telegram.ext package
22
====================
33

4+
.. automodule:: telegram.ext
5+
46
.. toctree::
57
:titlesonly:
68

‎telegram/_telegramobject.py

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -58,6 +58,12 @@ class TelegramObject:
5858
The :mod:`pickle` and :func:`~copy.deepcopy` behavior of objects of this type are defined by
5959
:meth:`__getstate__`, :meth:`__setstate__` and :meth:`__deepcopy__`.
6060
61+
Tip:
62+
Objects of this type can be serialized via Python's :mod:`pickle` module and pickled
63+
objects from one version of PTB are usually loadable in future versions. However, we can
64+
not guarantee that this compatibility will always be provided. At least a manual one-time
65+
conversion of the data may be needed on major updates of the library.
66+
6167
.. versionchanged:: 20.0
6268
6369
* Removed argument and attribute ``bot`` for several subclasses. Use

‎telegram/error.py

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -55,6 +55,12 @@ class TelegramError(Exception):
5555
"""
5656
Base class for Telegram errors.
5757
58+
Tip:
59+
Objects of this type can be serialized via Python's :mod:`pickle` module and pickled
60+
objects from one version of PTB are usually loadable in future versions. However, we can
61+
not guarantee that this compatibility will always be provided. At least a manual one-time
62+
conversion of the data may be needed on major updates of the library.
63+
5864
.. seealso:: :wiki:`Exceptions, Warnings and Logging <Exceptions%2C-Warnings-and-Logging>`
5965
"""
6066

0 commit comments

Comments
 (0)
0