[openstack-dev] [oslo] Document API changes using Sphinx markups

Clint Byrum clint at fewbar.com
Tue Jul 7 16:13:39 UTC 2015


Excerpts from Victor Stinner's message of 2015-07-07 08:22:26 -0700:
> Hi,
> 
> Oslo libraries become more and more stable, cool :-) Sometimes, we have 
> to modify APIs, to fix bugs, to deprecate functions, to add new function 
> parameters, etc. It would be cool to _document_ these changes. Sphinx 
> provides nice markups to document API changes:
> 
>     http://sphinx-doc.org/markup/para.html
> 
> We can try to ensure that API changes are documented in reviews, or 
> maybe also document old changes.
> 
> Examples:
> 
> .. versionadded:: 2.5
>     The *spam* parameter.
> 
> .. versionadded:: 2.6
>     The function now returns an integer.
> 
> .. deprecated:: 3.1
>     Use :func:`spam` instead.
> 
> I noticed that the deprecated markup is already used in oslo.utils doc:
> 
> http://docs.openstack.org/developer/oslo.utils/api/timeutils.html#oslo_utils.timeutils.isotime
> 

This is great information, thank you.

Any time we have versions appearing in code or docs, I cringe, because
versions and releasing are separate from coding and documenting.
If I'm adding a parameter today in the latest commit after 1.0.0, I
really don't know if the next version released will be 1.1.0 or 2.0.0
(I do know it won't be 1.0.1 because I have changed the API!).

Or do we just make a rule that you _do_ get to choose the version bump
in the commit that changes the API, and if you say 1.1.0, and it becomes
2.0.0 before release, thats ok because the versionadded is still accurate
even if 1.1.0 didn't release?



More information about the OpenStack-dev mailing list