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. | ||||
