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

Victor Stinner vstinner at redhat.com
Tue Jul 7 16:23:28 UTC 2015

Le 07/07/2015 18:13, Clint Byrum a écrit :
> 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!).

I propose to bet that the next version will be N+1. For example, 1.0 is 
followed by 1.1.

If we decide to get a different version number like 2.0, it's easy to 
replace "1.1" with "2.0" in all markups, because markups are easy to be 
matched by patterns.

Example of regex:

"\.\. (versionadded|versionchanged|deprecated)::"

We can easily write a tool to automate this operation.

Oh by the way, Sphinx provides tools to generate a changelog from all 
these markups. We may use them to check that we correctly updated all 


More information about the OpenStack-dev mailing list