Show More
api.rst
60 lines
| 1.2 KiB
| text/x-rst
|
RstLexer
r1 | ||||
r1120 | =================== | |||
CONTRIBUTING TO API | ||||
=================== | ||||
r1 | ||||
Naming conventions | ||||
================== | ||||
We keep the calls in the form ``{verb}_{noun}``. | ||||
Change and Deprecation | ||||
====================== | ||||
API deprecation is documented in the section :ref:`deprecated` together with | ||||
other notes about deprecated parts of the application. | ||||
Deprecated API calls | ||||
-------------------- | ||||
- Make sure to add them into the section :ref:`deprecated`. | ||||
- Use `deprecated` inside of the call docstring to make our users aware of the | ||||
deprecation:: | ||||
.. deprecated:: 1.2.3 | ||||
Use `new_call_name` instead to fetch this information. | ||||
- Make sure to log on level `logging.WARNING` a message that the API call or | ||||
specific parameters are deprecated. | ||||
- If possible return deprecation information inside of the result from the API | ||||
call. Use the attribute `_warning_` to contain a message. | ||||
Changed API calls | ||||
----------------- | ||||
- If the change is significant, consider to use `versionchanged` in the | ||||
docstring:: | ||||
.. versionchanged:: 1.2.3 | ||||
Optional explanation if reasonable. | ||||
Added API calls | ||||
--------------- | ||||
- Use `versionadded` to document since which version this API call is | ||||
available:: | ||||
.. versionadded:: 1.2.3 | ||||
Optional explanation if reasonable. | ||||