mirror of
https://github.com/python-telegram-bot/python-telegram-bot.git
synced 2024-12-28 07:20:17 +01:00
Add a Stability Policy (#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>
This commit is contained in:
Bibo-Joshi
GitHub
parent
66b6d3c497
commit
1c6ae435bf
9 changed files with 218 additions and 43 deletions
55
.github/CONTRIBUTING.rst
vendored
55
.github/CONTRIBUTING.rst
vendored
|
|
@ -67,6 +67,7 @@ Here's how to make a one-off code change.
|
|||
$ git checkout -b your-branch-name
|
||||
|
||||
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.
|
||||
We also have a check-list for PRs `below`_.
|
||||
|
||||
- You can refer to relevant issues in the commit message by writing, e.g., "#105".
|
||||
|
||||
|
|
@ -80,7 +81,7 @@ Here's how to make a one-off code change.
|
|||
|
||||
- The following exceptions to the above (Google's) style guides applies:
|
||||
|
||||
- Documenting types of global variables and complex types of class members can be done using the Sphinx docstring convention.
|
||||
- Documenting types of global variables and complex types of class members can be done using the Sphinx docstring convention.
|
||||
|
||||
- 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.
|
||||
|
||||
|
|
@ -121,11 +122,11 @@ Here's how to make a one-off code change.
|
|||
|
||||
- When your reviewer has reviewed the code, you'll get a notification. You'll need to respond in two ways:
|
||||
|
||||
- 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)".
|
||||
- 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)".
|
||||
|
||||
- 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.
|
||||
- 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.
|
||||
|
||||
- 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.
|
||||
- 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.
|
||||
|
||||
- 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:
|
||||
|
||||
|
|
@ -150,6 +151,51 @@ Here's how to make a one-off code change.
|
|||
|
||||
7. **Celebrate.** Congratulations, you have contributed to ``python-telegram-bot``!
|
||||
|
||||
Check-list for PRs
|
||||
------------------
|
||||
|
||||
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.
|
||||
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.
|
||||
|
||||
- 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)
|
||||
- Created new or adapted existing unit tests
|
||||
- Documented code changes according to the `CSI standard <https://standards.mousepawmedia.com/en/stable/csi.html>`__
|
||||
- Added myself alphabetically to ``AUTHORS.rst`` (optional)
|
||||
- Added new classes & modules to the docs and all suitable ``__all__`` s
|
||||
- Checked the `Stability Policy <https://docs.python-telegram-bot.org/stability_policy.html>`_ in case of deprecations or changes to documented behavior
|
||||
|
||||
**If the PR contains API changes (otherwise, you can ignore this passage)**
|
||||
|
||||
- Checked the Bot API specific sections of the `Stability Policy <https://docs.python-telegram-bot.org/stability_policy.html>`_
|
||||
|
||||
- New classes:
|
||||
|
||||
- Added ``self._id_attrs`` and corresponding documentation
|
||||
- ``__init__`` accepts ``api_kwargs`` as kw-only
|
||||
|
||||
- Added new shortcuts:
|
||||
|
||||
- In :class:`~telegram.Chat` & :class:`~telegram.User` for all methods that accept ``chat/user_id``
|
||||
- In :class:`~telegram.Message` for all methods that accept ``chat_id`` and ``message_id``
|
||||
- For new :class:`~telegram.Message` shortcuts: Added ``quote`` argument if methods accepts ``reply_to_message_id``
|
||||
- In :class:`~telegram.CallbackQuery` for all methods that accept either ``chat_id`` and ``message_id`` or ``inline_message_id``
|
||||
|
||||
- If relevant:
|
||||
|
||||
- Added new constants at :mod:`telegram.constants` and shortcuts to them as class variables
|
||||
- Link new and existing constants in docstrings instead of hard-coded numbers and strings
|
||||
- Add new message types to :attr:`telegram.Message.effective_attachment`
|
||||
- Added new handlers for new update types
|
||||
|
||||
- Add the handlers to the warning loop in the :class:`~telegram.ext.ConversationHandler`
|
||||
|
||||
- Added new filters for new message (sub)types
|
||||
- Added or updated documentation for the changed class(es) and/or method(s)
|
||||
- Added the new method(s) to ``_extbot.py``
|
||||
- Added or updated ``bot_methods.rst``
|
||||
- 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``
|
||||
- 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`
|
||||
|
||||
Documenting
|
||||
===========
|
||||
|
||||
|
|
@ -266,3 +312,4 @@ break the API classes. For example:
|
|||
.. _`CSI`: https://standards.mousepawmedia.com/en/stable/csi.html
|
||||
.. _`section`: #documenting
|
||||
.. _`testing page`: https://github.com/python-telegram-bot/python-telegram-bot/blob/master/tests/README.rst
|
||||
.. _`below`: #check-list-for-prs
|
||||
|
|
|
|||
38
.github/pull_request_template.md
vendored
38
.github/pull_request_template.md
vendored
|
|
@ -1,38 +1,6 @@
|
|||
<!--
|
||||
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).
|
||||
Hey! You're PRing? Cool!
|
||||
Please be sure to check out our contribution guide (https://github.com/python-telegram-bot/python-telegram-bot/blob/master/.github/CONTRIBUTING.rst).
|
||||
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.
|
||||
-->
|
||||
|
||||
### Checklist for PRs
|
||||
|
||||
- [ ] Added `.. versionadded:: version`, `.. versionchanged:: version` or `.. deprecated:: version` to the docstrings for user facing changes (for methods/class descriptions, arguments and attributes)
|
||||
- [ ] Created new or adapted existing unit tests
|
||||
- [ ] Documented code changes according to the [CSI standard](https://standards.mousepawmedia.com/en/stable/csi.html)
|
||||
- [ ] Added myself alphabetically to `AUTHORS.rst` (optional)
|
||||
- [ ] Added new classes & modules to the docs and all suitable `__all__` s
|
||||
|
||||
|
||||
### If the PR contains API changes (otherwise, you can delete this passage)
|
||||
|
||||
* New classes:
|
||||
- [ ] Added `self._id_attrs` and corresponding documentation
|
||||
- [ ] `__init__` accepts `api_kwargs` as kw-only
|
||||
|
||||
* Added new shortcuts:
|
||||
- [ ] In `Chat` & `User` for all methods that accept `chat/user_id`
|
||||
- [ ] In `Message` for all methods that accept `chat_id` and `message_id`
|
||||
- [ ] For new `Message` shortcuts: Added `quote` argument if methods accepts `reply_to_message_id`
|
||||
- [ ] In `CallbackQuery` for all methods that accept either `chat_id` and `message_id` or `inline_message_id`
|
||||
|
||||
* If relevant:
|
||||
|
||||
- [ ] Added new constants at `telegram.constants` and shortcuts to them as class variables
|
||||
- [ ] Link new and existing constants in docstrings instead of hard coded number and strings
|
||||
- [ ] Add new message types to `Message.effective_attachment`
|
||||
- [ ] Added new handlers for new update types
|
||||
- [ ] Add the handlers to the warning loop in the `ConversationHandler`
|
||||
- [ ] Added new filters for new message (sub)types
|
||||
- [ ] Added or updated documentation for the changed class(es) and/or method(s)
|
||||
- [ ] Added the new method(s) to `_extbot.py`
|
||||
- [ ] Added or updated `bot_methods.rst`
|
||||
- [ ] 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`
|
||||
- [ ] 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`
|
||||
|
|
|
|||
|
|
@ -1,3 +1,5 @@
|
|||
.. _ptb-changelog:
|
||||
|
||||
=========
|
||||
Changelog
|
||||
=========
|
||||
|
|
|
|||
|
|
@ -8,7 +8,7 @@ aspect of the Telegram Bot API while others focus on one of the
|
|||
mechanics of this library. Except for the
|
||||
:any:`examples.rawapibot` example, they all use the high-level
|
||||
framework this library provides with the
|
||||
:any:`telegram.ext <telegram.ext>` submodule.
|
||||
:mod:`telegram.ext` submodule.
|
||||
|
||||
All examples are licensed under the `CC0
|
||||
License <https://github.com/python-telegram-bot/python-telegram-bot/blob/master/examples/LICENSE.txt>`__
|
||||
|
|
|
|||
|
|
@ -27,11 +27,12 @@
|
|||
:hidden:
|
||||
:caption: Project
|
||||
|
||||
stability_policy
|
||||
changelog
|
||||
coc
|
||||
contributing
|
||||
testing
|
||||
Website <https://python-telegram-bot.org>
|
||||
GitHub Repository <https://github.com/python-telegram-bot/python-telegram-bot/>
|
||||
Telegram Channel <https://t.me/pythontelegrambotchannel/>
|
||||
Telegram User Group <https://t.me/pythontelegrambotgroup/>
|
||||
coc
|
||||
contributing
|
||||
testing
|
||||
|
|
|
|||
143
docs/source/stability_policy.rst
Normal file
143
docs/source/stability_policy.rst
Normal file
|
|
@ -0,0 +1,143 @@
|
|||
Stability Policy
|
||||
================
|
||||
|
||||
.. important::
|
||||
|
||||
This stability policy is in place since version NEXT.VERSION.
|
||||
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.
|
||||
Please also refer to the :ref:`changelog <ptb-changelog>`.
|
||||
|
||||
.. caution::
|
||||
|
||||
Large parts of the :mod:`telegram` package are the Python representations of the Telegram Bot API, whose stability policy PTB can not influence.
|
||||
This policy hence includes some special cases for those parts.
|
||||
|
||||
What does this policy cover?
|
||||
----------------------------
|
||||
|
||||
This policy includes any API or behavior that is covered in this documentation.
|
||||
This covers both the :mod:`telegram` package and the :mod:`telegram.ext` package.
|
||||
|
||||
What doesn't this policy cover?
|
||||
-------------------------------
|
||||
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
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.
|
||||
We may provide a way to convert pickled objects from one version to another, but this is not guaranteed.
|
||||
|
||||
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.
|
||||
This also applies to functions or attributes marked as final in the sense of `PEP 591 <https://www.python.org/dev/peps/pep-0591/>`__.
|
||||
|
||||
PTB has dependencies to third-party packages.
|
||||
The versions that PTB uses of these third-party packages may change if that does not affect PTBs public API.
|
||||
|
||||
PTB does not give guarantees about which Python versions are supported.
|
||||
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.
|
||||
|
||||
.. _bot-api-functionality-1:
|
||||
|
||||
Bot API Functionality
|
||||
~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
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.
|
||||
Changes in this regard will be documented in the affected classes.
|
||||
Note that equality comparison with objects that where serialized by an older version of PTB may hence give unexpected results.
|
||||
|
||||
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.
|
||||
While we try to make such changes backward compatible, this is not always possible or only with significant effort.
|
||||
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.
|
||||
We highly recommend using keyword arguments, which can help make such changes non-breaking on your end.
|
||||
|
||||
..
|
||||
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
|
||||
|
||||
When the Bot API changes attributes of classes, the method :meth:`telegram.TelegramObject.to_dict` will change as necessary to reflect these changes.
|
||||
In particular, attributes deprecated by Telegram will be removed from the returned dictionary.
|
||||
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.
|
||||
Since attributes of the classes in the :mod:`telegram` package are not writable, we may change them to properties where appropriate.
|
||||
|
||||
Development Versions
|
||||
~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Pre-releases marked as alpha, beta or release candidate are not covered by this policy.
|
||||
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.
|
||||
|
||||
Security
|
||||
~~~~~~~~
|
||||
|
||||
We make exceptions from our stability policy for security.
|
||||
We will violate this policy as necessary in order to resolve a security issue or harden PTB against a possible attack.
|
||||
|
||||
Versioning
|
||||
----------
|
||||
|
||||
PTB uses a versioning scheme that roughly follows `https://semver.org/ <https://semver.org/>`_, although it may not be quite as strict.
|
||||
|
||||
Given a version of PTB X.Y.Z,
|
||||
|
||||
- X indicates the major version number.
|
||||
This is incremented when backward incompatible changes are introduced.
|
||||
- Y indicates the minor version number.
|
||||
This is incremented when new functionality or backward compatible changes are introduced by PTB.
|
||||
*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>`.
|
||||
- Z is the patch version.
|
||||
This is incremented if backward compatible bug fixes or smaller changes are introduced.
|
||||
If this number is 0, it can be omitted, i.e. we just write X.Y instead of X.Y.0.
|
||||
|
||||
Deprecation
|
||||
~~~~~~~~~~~
|
||||
|
||||
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.
|
||||
In those cases, we follow a deprecation schedule as detailed below.
|
||||
|
||||
Functionality is marked as deprecated by a corresponding note in the release notes and the documentation.
|
||||
Where possible, a :class:`~telegram.warnings.PTBDeprecationWarning` is issued when deprecated functionality is used, but this is not mandatory.
|
||||
|
||||
From time to time, we may decide to deprecate an API that is particularly widely used.
|
||||
In these cases, we may decide to provide an extended deprecation period, at our discretion.
|
||||
|
||||
With version 20.0.0, PTB introduced major structural breaking changes without the above deprecation period.
|
||||
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>`_.
|
||||
|
||||
Non-Bot API Functionality
|
||||
#########################
|
||||
|
||||
Starting with version NEXT.VERSION, deprecated functionality will stay available for the current and the next major version.
|
||||
For example:
|
||||
|
||||
- In PTB v20.1.1 the feature exists
|
||||
- In PTB v20.1.2 or v20.2.0 the feature is marked as deprecated
|
||||
- In PTB v21.*.* the feature is marked as deprecated
|
||||
- In PTB v22.0 the feature is removed or changed
|
||||
|
||||
.. _bot-api-versioning:
|
||||
|
||||
Bot API Functionality
|
||||
#####################
|
||||
|
||||
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.
|
||||
|
||||
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.
|
||||
More precisely, two cases are possible, for which we show examples below.
|
||||
|
||||
Case 1
|
||||
^^^^^^
|
||||
|
||||
- In PTB v20.1 the feature exists
|
||||
- Bot API version 6.6 is released and deprecates the feature
|
||||
- PTB v20.2 adds support for Bot API 6.6 and the feature is
|
||||
marked as deprecated
|
||||
- In PTB v21.0 the feature is removed or changed
|
||||
|
||||
Case 2
|
||||
^^^^^^
|
||||
|
||||
- In PTB v20.1 the feature exists
|
||||
- Bot API version 6.6 is released and deprecates the feature
|
||||
- PTB v20.2 adds support for Bot API version 6.6 and the feature is marked as deprecated
|
||||
- In PTB v20.2.* and v20.3.* the feature is marked as deprecated
|
||||
- Bot API version 6.7 is released
|
||||
- PTB v20.4 adds support for Bot API version 6.7 and the feature is removed or changed
|
||||
|
|
@ -1,6 +1,8 @@
|
|||
telegram.ext package
|
||||
====================
|
||||
|
||||
.. automodule:: telegram.ext
|
||||
|
||||
.. toctree::
|
||||
:titlesonly:
|
||||
|
||||
|
|
|
|||
|
|
@ -58,6 +58,12 @@ class TelegramObject:
|
|||
The :mod:`pickle` and :func:`~copy.deepcopy` behavior of objects of this type are defined by
|
||||
:meth:`__getstate__`, :meth:`__setstate__` and :meth:`__deepcopy__`.
|
||||
|
||||
Tip:
|
||||
Objects of this type can be serialized via Python's :mod:`pickle` module and pickled
|
||||
objects from one version of PTB are usually loadable in future versions. However, we can
|
||||
not guarantee that this compatibility will always be provided. At least a manual one-time
|
||||
conversion of the data may be needed on major updates of the library.
|
||||
|
||||
.. versionchanged:: 20.0
|
||||
|
||||
* Removed argument and attribute ``bot`` for several subclasses. Use
|
||||
|
|
|
|||
|
|
@ -55,6 +55,12 @@ class TelegramError(Exception):
|
|||
"""
|
||||
Base class for Telegram errors.
|
||||
|
||||
Tip:
|
||||
Objects of this type can be serialized via Python's :mod:`pickle` module and pickled
|
||||
objects from one version of PTB are usually loadable in future versions. However, we can
|
||||
not guarantee that this compatibility will always be provided. At least a manual one-time
|
||||
conversion of the data may be needed on major updates of the library.
|
||||
|
||||
.. seealso:: :wiki:`Exceptions, Warnings and Logging <Exceptions%2C-Warnings-and-Logging>`
|
||||
"""
|
||||
|
||||
|
|
|
|||
Loading…
Reference in a new issue