Document the preferred naming convention for new API

[erlend-aasland]

We need a naming convention for new versions of an existing API. Illustrated by an example:

PyFoo_Bar() is a problematic API; it returns a borrowed reference, suppresses arbitrary exceptions, and requires callers to check PyErr_Occurred() to find out if an exception was raised. A PR now exists to replace PyFoo_Bar() with a new and non-problematic API, but unfortunately that PR cannot be merged, because unlike the implementation of the new API, there is no consensus on the naming of the new API; after all, PyFoo_Bar() is the perfect name. How to proceed?

@vstinner has suggested to add a Ref suffix when fixing APIs that return borrowed references¹.

I propose to follow the SQLite practise of adding a version specifier² if an API is replaced.

Footnotes

1. PyFoo_Bar would become PyFoo_BarRef, since it now returns a strong reference. ↩

2. PyFoo_Bar would become PyFoo_Bar_v2. ↩

[erlend-aasland]

In capi-workgroup/problems#52 (comment), @vstinner points out that there is already precedent for using the number suffix in the Python C API.

[erlend-aasland]

Closing as not planned. See also capi-workgroup/problems#52 (comment).